chore(docs): generate doc index

It contains links to all generated API docs, in a style similar to the
standard rust API docs. Thank you, shared CSS !

Makefile

@@ -1,4 +1,4 @@
-.PHONY:  json-to-xml clean help api-deps regen-apis license update-json cargo
+.PHONY:  json-to-xml clean help api-deps regen-apis license update-json rebuild-docs
 .SUFFIXES:
 
 include Makefile.helpers
@@ -20,12 +20,16 @@ API_LIST = etc/api/api-list.yaml
 API_JSON_FILES = $(shell find etc -type f -name '*-api.json')
 MAKO_LIB_DIR = $(MAKO_SRC)/lib
 MAKO_LIB_FILES = $(shell find $(MAKO_LIB_DIR) -type f -name '*.*')
+MAKO = PYTHONPATH=$(MAKO_LIB_DIR) $(TPL)
+MAKO_STANDARD_DEPENDENCIES = $(API_SHARED_INFO) $(MAKO_LIB_FILES) $(MAKO_RENDER)
 
 help:
 	$(info using template engine: '$(TPL)')
 	$(info )
 	$(info Targets)
-	$(info apis         -    make all APIs)
+	$(info docs         -   cargo-doc on all APIs, assemble them together and generate index)
+	$(info rebuild-docs -   clear out docs folder and regenerate. Should be done if API count changes, and before gh-import)
+	$(info apis         -   make all APIs)
 	$(info cargo        -   run cargo on all APIs, use ARGS="args ..." to specify cargo arguments)
 	$(info regen-apis   -   clear out all generated apis, and regenerate them)
 	$(info clean-apis   -   delete all generated APIs)
@@ -41,8 +45,8 @@ $(PYTHON):
 
 $(MAKO_RENDER): $(PYTHON)
 
-$(API_DEPS): $(API_SHARED_INFO) $(API_DEPS_TPL) $(MAKO_LIB_FILES) $(MAKO_RENDER) $(API_LIST)
-	PYTHONPATH=$(MAKO_LIB_DIR) $(TPL) --template-dir '.' -io $(API_DEPS_TPL)=$@ --data-files $(API_SHARED_INFO) $(API_LIST)
+$(API_DEPS): $(API_DEPS_TPL) $(MAKO_STANDARD_DEPENDENCIES) $(API_LIST)
+	$(MAKO) --template-dir '.' -io $(API_DEPS_TPL)=$@ --data-files $(API_SHARED_INFO) $(API_LIST)
 
 api-deps: $(API_DEPS)
 
@@ -51,8 +55,8 @@ $(API_LIST): $(API_VERSION_GEN)
 
 include $(API_DEPS)
 
-LICENSE.md: $(MAKO_SRC)/LICENSE.md.mako $(API_SHARED_INFO)
-	PYTHONPATH=$(MAKO_LIB_DIR) $(TPL) -io $<=$@ --data-files $(API_SHARED_INFO)
+LICENSE.md: $(MAKO_SRC)/LICENSE.md.mako $(API_SHARED_INFO) $(MAKO_RENDER)
+	$(MAKO) -io $<=$@ --data-files $(API_SHARED_INFO)
 
 license: LICENSE.md
 
@@ -62,7 +66,7 @@ clean: clean-apis
 	-rm -Rf $(VENV_DIR)
 	-rm $(API_DEPS)
 
+rebuild-docs: docs-clean docs
+
 update-json:
 	etc/bin/update-json.sh $(GOOGLE_GO_APIS_REPO) etc/api
-
-

src/mako/deps.mako

@@ -2,7 +2,16 @@
 # This file was generated automatically by '${self.uri}'
 # DO NOT EDIT !
 
-<%api_info=[]%>\
+<%
+	import os
+
+	api_info=[]
+	doc_root = directories.output + '/doc'
+	doc_index = doc_root + '/index.html'
+
+	to_doc_root = lambda gen_root, api_name: gen_root + '/target/doc/' + api_name
+	central_api_index = lambda api_name: doc_root + '/' + api_name + '/index.html'
+%>\
 % for an, versions in api.list.iteritems():
 % if an in api.get('blacklist', list()):
 <% continue %>\
@@ -11,21 +20,26 @@
 <%
 	import util
 	import os
-	gen_root = directories.output + '/' + an + util.to_api_version(version)
-	gen_root_stamp = gen_root + '/.timestamp'
 	api_name = util.library_name(an, version)
+	gen_root = directories.output + '/' + api_name
+	gen_root_stamp = gen_root + '/.timestamp'
 	api_common = gen_root + '/src/cmn.rs'
 	api_clean = api_name + '-clean'
 	api_cargo = api_name + '-cargo'
+	api_doc = api_name + '-doc'
+
+	api_doc_root = to_doc_root(gen_root, api_name)
+	api_doc_index = api_doc_root + '/index.html'
+
 	# source, destination of individual output files
 	sds = [(directories.mako_src + '/' + i.source + '.mako', gen_root + '/' + i.get('output_dir', '') + '/' + i.source) 
 																								for i in api.templates]
 	api_json = directories.api_base + '/' + an + '/' + version + '/' + an + '-api.json'
 	api_json_overrides = os.path.dirname(api_json) + '/' + an + '-api_overrides.json'
-	api_json_inputs = api_json + " $(API_SHARED_INFO)"
+	api_json_inputs = api_json
 	if os.path.isfile(api_json_overrides):
 		api_json_inputs += ' ' + api_json_overrides
-	api_info.append((api_name, api_clean, api_cargo, gen_root))
+	api_info.append((api_name, api_clean, api_cargo, api_doc, gen_root))
 
 	space_join = lambda i: ' '.join(a[i] for a in api_info)
 %>\
@@ -34,22 +48,44 @@ ${api_common}: $(RUST_SRC)/cmn.rs $(lastword $(MAKEFILE_LIST)) ${gen_root_stamp}
 	@ echo "// DO NOT EDIT"  >> $@
 	@cat $< >> $@
 
-${gen_root_stamp}: ${' '.join(i[0] for i in sds)} ${api_json_inputs} $(MAKO_LIB_FILES) $(MAKO_RENDER)
+${gen_root_stamp}: ${' '.join(i[0] for i in sds)} ${api_json_inputs} $(MAKO_STANDARD_DEPENDENCIES)
 	@echo Generating ${api_name}
-	@PYTHONPATH=$(MAKO_LIB_DIR) $(TPL) --template-dir '.' --var OUTPUT_DIR=$@ -io ${' '.join("%s=%s" % (s, d) for s, d in sds)} --data-files ${api_json_inputs}
+	@$(MAKO) --template-dir '.' --var OUTPUT_DIR=$@ -io ${' '.join("%s=%s" % (s, d) for s, d in sds)} --data-files ${api_json_inputs}
 	@touch $@
 
-${api_name}: ${gen_root_stamp} ${api_common}
+${api_name}: ${api_common}
 
 ${api_cargo}: ${api_name}
 	cd ${gen_root} && cargo $(ARGS)
 
+${api_doc_index}: ${gen_root_stamp}
+	cd ${gen_root} && cargo doc
+	@echo "Docs for ${api_name} at $@"
+
+${api_doc}: ${api_doc_index}
+
+${central_api_index(api_name)}: ${api_doc_index}
+	@mkdir -p ${doc_root}
+	cp -Rf ${os.path.dirname(to_doc_root(gen_root, api_name))}/* ${doc_root}
+
 ${api_clean}:
 	-rm -Rf ${gen_root}
 % endfor
 % endfor
 
-.PHONY += $(.PHONY) help-api clean-apis apis ${space_join(0)} ${space_join(1)} ${space_join(2)}
+clean-apis: ${space_join(1)} docs-clean
+cargo: ${space_join(2)}
+apis: ${space_join(0)}
+
+${doc_index}: ${' '.join(central_api_index(a[0]) for a in api_info)} $(MAKO_STANDARD_DEPENDENCIES)
+	$(MAKO) --var DOC_ROOT=${doc_root} -io $(MAKO_SRC)/index.html.mako=$@ --data-files $(API_SHARED_INFO) $(API_LIST)
+
+docs: ${doc_index}
+docs-clean:
+	@rm -Rf ${doc_root}	
+
+
+.PHONY += $(.PHONY) help-api clean-apis cargo apis docs docs-clean ${space_join(0)} ${space_join(1)} ${space_join(2)} ${space_join(3)}
 
 help-api:
 	$(info apis       -    make all APIs)
@@ -57,8 +93,5 @@ help-api:
 	$(info ${a[0]}    -    build the ${a[0]} api)
 	$(info ${a[1]}    -    clean all generated files of the ${a[0]} api)
 	$(info ${a[2]}    -    run cargo on the ${a[0]} api, using given ARGS="arg1 ...")
-% endfor
-
-clean-apis: ${space_join(1)}
-cargo: ${space_join(2)}
-apis: ${space_join(0)}
+	$(info ${a[3]}    -    run cargo doc on the ${a[0]}")
+% endfor

src/mako/index.html.mako

@@ -0,0 +1,42 @@
+<%
+    import os
+    from util import library_name
+
+    def api_index(name, version):
+        index_file_path = library_name(name, version) + '/index.html'
+        if os.path.isfile(DOC_ROOT + '/' + index_file_path):
+            return index_file_path
+        return None
+
+    title = 'Google Rust Client API Docs'
+%>\
+<!DOCTYPE html>
+<!--
+DO NOT EDIT !
+This file was generated automatically by '${self.uri}'
+DO NOT EDIT !
+-->
+<html>
+<head>
+<link rel="stylesheet" href="main.css">
+<style type="text/css">
+.mod {
+  color: #4d76ae;
+}
+</style>
+	<title>${title}</title>
+</head>
+<body>
+<H1>${title}</H1>
+<ul>
+% for an in sorted(api.list.keys()):
+    % for v in api.list[an]:
+    % if not api_index(an, v):
+        <% continue %>\
+    % endif
+    <a class="mod" href="${api_index(an, v)}" title="API docs for ${an} ${v}">${an} ${v}</a><br/>
+    % endfor
+% endfor
+</ul>
+</body>
+</html>