doc(index): link to doc.rs for APIs

We also link more specifically to crates.io.

Some debt was taken on as the build_version is special and
duplicated right now.

etc/api/type-api.yaml

@@ -25,6 +25,7 @@ make:
     - source: build.rs
       output_dir: src
 cargo:
+  build_version: "1.0.0"
   build_script: src/build.rs
   keywords: [protocol, web, api]
   doc_base_url: https://docs.rs

src/mako/cli/lib/argparse.mako

@@ -84,7 +84,7 @@ Configuration:
 <%def name="new(c)" buffered="True">\
 <%
     doc_base_url = cargo.doc_base_url + '/' + os.path.dirname(api_index(cargo.doc_base_url, name,
-                                                                        version, make, check_exists=False))
+                                                                        version, make, cargo, revision, check_exists=False))
     url_info = "All documentation details can be found at " + doc_base_url
 
     # list of tuples

src/mako/deps.mako

@@ -74,7 +74,7 @@
 	# source, destination of individual output files
 	sds = [(directories.mako_src + '/' + make.id + '/' + i.source + '.mako', gen_root + '/' +
 		   i.get('output_dir', '') + '/' + i.source.strip('../')) for i in make.templates]
-	api_json = directories.api_base + '/' + an + '/' + version + '/' + an + '-api.json'
+	api_json = util.api_json_path(directories.api_base, an, version)
 	api_meta_dir = os.path.dirname(api_json)
 	api_crate_publish_file = api_meta_dir + '/crates/' + util.crate_version(cargo.build_version +
 			make.aggregated_target_suffix, json.load(open(api_json, 'r')).get('revision', '00000000'))
@@ -136,7 +136,7 @@ publish${agsuffix}: | gen-all${agsuffix} ${space_join(4)}
 gen-all${agsuffix}: ${space_join(0)}
 
 % if global_targets:
-${doc_index}: ${' '.join('docs-' + api_name for api_name in make.types)} ${' '.join(gen_type_cfg_path(api_name) for api_name in make.types)}
+${doc_index}: docs-cli ${gen_type_cfg_path('cli')}
 	$(PYPATH) $(MAKO) --var DOC_ROOT=${doc_root} -io $(MAKO_SRC)/index.html.mako=$@ --data-files $(API_SHARED_INFO) $(API_LIST)
 	@echo Documentation index created at '$@'
 docs-all: ${doc_index}
@@ -174,9 +174,10 @@ help${agsuffix}:
 % for info in apis['items']:
 <%
 	import util
+	import os
 	name = util.normalize_library_name(info['name'])
-	target_dir = directories.api_base + '/' + name + '/' + info['version']
-	target = target_dir + '/' + name + '-api.json'
+	target = util.api_json_path(directories.api_base, name, info['version'])
+	target_dir = os.path.dirname(target)
 	## assure the target never actually exists to force him to wget whenver we ask !
 	fake_target = target + '-force'
 	## Some service urls have $ in them. This may cause the console to treat them as env vars.

src/mako/index.html.mako

@@ -1,7 +1,10 @@
 <%
+    import json
     import os
     import yaml
-    from util import (library_name, library_to_crate_name, gen_crate_dir, api_index, crates_io_url, program_name)
+    from util import (api_json_path, library_name, library_to_crate_name,
+                      gen_crate_dir, api_index, crates_io_url, program_name,
+                      crate_version)
 
     title = 'Google Service Documentation for Rust'
 
@@ -66,25 +69,28 @@ function selectElementContents(el) {
 % for an in sorted(api.list.keys()):
     % for v in api.list[an]:
         <% 
-            has_any_index = False
-            type_names = list()
-            for program_type, ad in tc.iteritems():
-                if api_index(DOC_ROOT, an, v, ad.make):
-                    has_any_index = True
-                    type_names.append(program_type)
+            type_names = tc.keys()
+            try:
+              fp = open(api_json_path(directories.api_base, an, v))
+              api_data = json.load(fp)
+            except (ValueError, IOError):
+              api_data = None
             # end for each type
         %>\
-        % if not has_any_index:
+        % if api_data is None:
             <% continue %>\
         % endif
         <span class="text">${an} ${v} (
         % for program_type in type_names:
-            <% ad = tc[program_type] %>
-            <a class="mod" href="${api_index(DOC_ROOT, an, v, ad.make)}" title="${ad.make.id.upper()} docs for the ${an} ${v}">${ad.make.id.upper()}</a>
+            <% 
+              ad = tc[program_type] 
+              revision = api_data.get('revision', None)
+            %>\
+            <a class="mod" href="${api_index(DOC_ROOT, an, v, ad.make, ad.cargo, revision)}" title="${ad.make.id.upper()} docs for the ${an} ${v}">${ad.make.id.upper()}</a>
             % if program_type == 'api':
-            <a href="${crates_io_url(an, v)}"><img src="${url_info.asset_urls.crates_img}" title="This API on crates.io" height="16" width="16"/></a>
+            <a href="${crates_io_url(an, v)}/${crate_version(ad.cargo.build_version, revision)}"><img src="${url_info.asset_urls.crates_img}" title="This API on crates.io" height="16" width="16"/></a>
             % else:
-            , <button class="mono" onclick="onClick(this)">cargo install ${library_to_crate_name(library_name(an, v))}-cli</button>
+            , <button class="mono" onclick="onClick(this)" title="Copy installation script to clipboard">cargo install ${library_to_crate_name(library_name(an, v))}-cli</button>
             % endif
             % if not loop.last:
 ,           

src/mako/lib/util.mako

@@ -31,12 +31,12 @@ ${util.library_to_crate_name(util.library_name(name, version), make.target_suffi
 % if make.id == 'cli':
 ${cargo.doc_base_url + '/' + util.to_extern_crate_name(self.crate_name())}\
 % else:
-${cargo.doc_base_url + '/' + self.crate_name() + '/' + self.crate_version()}\
+${util.docs_rs_url(cargo.doc_base_url, self.crate_name(), self.crate_version())}\
 % endif
 </%def>
 
 <%def name="crate_version()" buffered="True">\
-${util.crate_version(cargo.build_version, revision is UNDEFINED and '00000000' or revision)}\
+${util.crate_version(cargo.build_version, revision)}\
 </%def>
 
 ## All crates and standard `use` declaration, required for all examples

src/mako/lib/util.py

@@ -826,12 +826,18 @@ def library_to_crate_name(name, suffix=''):
 
 # return version like 0.1.0+2014031421
 def crate_version(build_version, revision):
-    return '%s+%s' % (build_version, revision)
+    return '%s+%s' % (build_version, isinstance(revision, basestring) and revision or '00000000')
 
 # return a crate name for us in extern crate statements
 def to_extern_crate_name(crate_name):
     return crate_name.replace('-', '_')
 
+def docs_rs_url(base_url, crate_name, version):
+    return base_url + '/' + crate_name + '/' + version
+    
+def crate_name(name, version, make):
+    return library_to_crate_name(library_name(name, version), make.target_suffix)
+    
 def gen_crate_dir(name, version, ti):
     return to_extern_crate_name(library_to_crate_name(library_name(name, version), ti.target_suffix))
 
@@ -841,15 +847,20 @@ def crates_io_url(name, version):
 def program_name(name, version):
     return library_name(name, version).replace('_', '-')
 
-def api_index(DOC_ROOT, name, version, ti, check_exists=True):
+def api_json_path(api_base, name, version):
+    return api_base + '/' + name + '/' + version + '/' + name + '-api.json'
+
+def api_index(DOC_ROOT, name, version, ti, cargo, revision, check_exists=True):
     crate_dir = gen_crate_dir(name, version, ti)
     if ti.documentation_engine == 'rustdoc':
-        index_file_path = crate_dir + '/index.html'
+        semver = crate_version(cargo.build_version, revision)
+        index_file_path = docs_rs_url(cargo.doc_base_url, crate_name(name, version, ti), semver)
+        return index_file_path
     else:
         index_file_path = crate_dir + '/' + 'index.html'
-    if not check_exists or os.path.isfile(os.path.join(DOC_ROOT, index_file_path)):
-        return index_file_path
-    return None
+        if not check_exists or os.path.isfile(os.path.join(DOC_ROOT, index_file_path)):
+            return index_file_path
+        return None
 
 # return type name of a resource method builder, from a resource name
 def rb_type(r):