feat(mkdocs): mkdocs generator works now

It can be selected for each type of program we want to build, and makes
sense for everything that is not a library.

We also tried to unify names and folders a bit more, even though there
certainly is more work to be done to be fully non-redundant.

Fixes #43

.gitignore

@@ -6,6 +6,7 @@ gen/*-cli/
 *.go
 *.pyc
 **target/
+**build_html/
 .*.deps
 **Cargo.lock
 *.sublime-workspace

Makefile

@@ -8,6 +8,7 @@ PIP := $(VENV_DIR)/bin/pip
 MAKO_RENDER := etc/bin/mako-render
 API_VERSION_GEN := etc/bin/api_version_to_yaml.py
 TPL := $(PYTHON) $(MAKO_RENDER)
+MKDOCS := $(shell pwd)/$(VENV_DIR)/bin/mkdocs
 
 MAKO_SRC = src/mako
 RUST_SRC = src/rust
@@ -52,7 +53,7 @@ $(VENV):
 
 $(PYTHON): $(VENV)
 	$(VENV) -p python2.7 $(VENV_DIR)
-	$(PIP) install mako pyyaml
+	$(PIP) install mako pyyaml 	mkdocs
 
 $(MAKO_RENDER): $(PYTHON)
 

etc/api/shared.yaml

@@ -16,6 +16,8 @@ directories:
   api_base: etc/api
   # all mako source files
   mako_src: src/mako
+  # The subdirectory to contain documentation from all APIs and related programs
+  doc_subdir: doc
 cargo:
   build_version: "0.1.1"
   repo_base_url: https://github.com/Byron/google-apis-rs

etc/api/type-api.yaml

@@ -17,6 +17,7 @@ make:
   aggregated_target_suffix: -api
   depends_on_suffix:
   global_targets: Yes
+  documentation_engine: rustdoc
   templates:
     # all output directories are relative to the one set for the respective API
     - source: README.md

etc/api/type-cli.yaml

@@ -1,12 +1,19 @@
+mkdocs:
+  ## A directory to bring us from the mkdocs invocation directory to the gen-root
+  gen_root_dir: ..
+  site_dir: build_html
 make:
   id: cli
   target_name: CLIs
   target_suffix: -cli
   aggregated_target_suffix: -cli
   depends_on_suffix: ''
+  documentation_engine: mkdocs
   templates:
     - source: ../LICENSE.md
     - source: ../Cargo.toml
+    - source: mkdocs.yml
+    - source: README.md
     - source: main.rs
       output_dir: src
 cargo:

gen/groupsmigration1-cli/Cargo.toml

@@ -7,7 +7,7 @@ name = "google-groupsmigration1-cli"
 version = "0.0.1+20140416"
 authors = ["Sebastian Thiel <byronimo@gmail>"]
 description = "A complete library to interact with Groups Migration (protocol v1)"
-repository = "https://github.com/Byron/google-apis-rs/tree/master/gen/groupsmigration1"
+repository = "https://github.com/Byron/google-apis-rs/tree/master/gen/groupsmigration1-cli"
 homepage = "https://developers.google.com/google-apps/groups-migration/"
 documentation = "http://byron.github.io/google-apis-rs/google-groupsmigration1-cli"
 license = "MIT"

gen/groupsmigration1-cli/README.md

@@ -0,0 +1 @@
+# HELLO GROUPSMIGRATION:V1

gen/groupsmigration1-cli/docs/index.md

@@ -0,0 +1 @@
+../README.md

gen/groupsmigration1-cli/mkdocs.yml

@@ -0,0 +1,16 @@
+site_name: Groups Migration v0.0.1+20140416
+site_url: http://byron.github.io/google-apis-rs/google-groupsmigration1-cli
+site_description: Write integrating applications with bcore
+
+repo_url: https://github.com/Byron/google-apis-rs/tree/master/gen/groupsmigration1-cli
+
+docs_dir: docs
+site_dir: build_html
+
+pages:
+- ['index.md', 'Home']
+
+theme: readthedocs
+
+copyright: Copyright © 2015, `Sebastian Thiel`
+

src/mako/cli/README.md.mako

@@ -0,0 +1 @@
+# HELLO ${id.upper()}

src/mako/cli/mkdocs.yml.mako

@@ -0,0 +1,19 @@
+<%! from util import put_and %>\
+<%namespace name="util" file="../lib/util.mako"/>\
+site_name: ${util.canonical_name()} v${util.crate_version()}
+site_url: ${cargo.doc_base_url}/${util.crate_name()}
+site_description: Write integrating applications with bcore
+
+repo_url: ${util.github_source_root_url()}
+
+docs_dir: docs
+site_dir: ${mkdocs.site_dir}
+
+pages:
+- ['index.md', 'Home']
+## - ['be.md', 'Features', 'BE - universal commandline tool']
+
+theme: readthedocs
+
+copyright: Copyright &copy; ${copyright.years}, ${put_and(["`%s`" % a for a in copyright.authors])}
+

src/mako/deps.mako

@@ -8,10 +8,16 @@
 	import json
 
 	api_info = []
-	doc_root = directories.output + '/doc'
+	doc_root = directories.output + '/' + directories.doc_subdir
 	doc_index = doc_root + '/index.html'
 
-	to_doc_root = lambda gen_root, crate_name: gen_root + '/target/doc/' + crate_name
+	def to_doc_root(gen_root, crate_name): 
+		if make.documentation_engine == 'mkdocs':
+			return gen_root + '/' + mkdocs.site_dir
+		else:
+			return gen_root + '/target/doc/' + crate_name
+	# end utility
+
 	central_api_index = lambda crate_name: doc_root + '/' + crate_name + '/index.html'
 
 	discovery_url = 'https://www.googleapis.com/discovery/v1/'
@@ -33,10 +39,10 @@
 	import json
 
 	api_name = util.library_name(an, version)
-	api_target = api_name + suffix
+	api_target = util.target_directory_name(an, version, suffix)
 	depends_on_target = ''
 	if make.depends_on_suffix is not None:
-		depends_on_target = api_name + make.depends_on_suffix
+		depends_on_target = util.target_directory_name(an, version, make.depends_on_suffix)
 	crate_name = util.library_to_crate_name(api_name, suffix)
 	gen_root = directories.output + '/' + api_target
 	gen_root_stamp = gen_root + '/.timestamp'
@@ -84,14 +90,24 @@ ${api_cargo}: ${api_target}
 	cd ${gen_root} && cargo $(ARGS)
 
 ${api_doc_index}: ${api_target}
+	% if make.documentation_engine == 'rustdoc':
 	cd ${gen_root} && cargo doc
 	@echo "Docs for ${api_target} at $@"
+	% else:
+	@echo mkdocs ${api_doc_index}
+	## Our README is the landing page, and thus will serve multiple roles at once !
+	@cd ${gen_root} && (mkdir -p docs && cd docs && ln -s ../README.md index.md &>/dev/null) || : && $(MKDOCS) build --clean
+	% endif
 
 ${api_doc}: ${api_doc_index}
 
 ${central_api_index(crate_name)}: ${api_doc_index}
 	@mkdir -p ${doc_root}
-	cp -Rf ${os.path.dirname(to_doc_root(gen_root, crate_name))}/* ${doc_root}
+	% if make.documentation_engine == 'rustdoc':
+	cp -Rf ${os.path.dirname(api_doc_root)}/* ${doc_root}
+	% else:
+	cp -Rf ${api_doc_root} ${doc_root}
+	% endif
 
 ${api_clean}:
 	-rm -Rf ${gen_root}

src/mako/lib/util.mako

@@ -16,7 +16,7 @@ ${v[1:]}\
 </%def>
 
 <%def name="github_source_root_url()" buffered="True">\
-${cargo.repo_base_url}/tree/master/${directories.output}/${self.library_name()}\
+${cargo.repo_base_url}/tree/master/${directories.output}/${util.target_directory_name(name, version, make.target_suffix)}\
 </%def>
 
 <%def name="library_name()" buffered="True">\

src/mako/lib/util.py

@@ -799,6 +799,9 @@ def library_name(name, version):
         version = 'v' + version
     return normalize_library_name(name) + version
 
+def target_directory_name(name, version, suffix):
+    return library_name(name, version) + suffix
+
 # return crate name for given result of `library_name()`
 def library_to_crate_name(name, suffix=''):
     return 'google-' + name + suffix