From fad9d3b0ca3f588f65faf6ec46caf51a7ca1c239 Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Sat, 24 Dec 2016 13:30:39 +0100 Subject: [PATCH] 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 | 1 + src/mako/cli/lib/argparse.mako | 2 +- src/mako/deps.mako | 9 +++++---- src/mako/index.html.mako | 30 ++++++++++++++++++------------ src/mako/lib/util.mako | 4 ++-- src/mako/lib/util.py | 23 +++++++++++++++++------ 6 files changed, 44 insertions(+), 25 deletions(-) diff --git a/etc/api/type-api.yaml b/etc/api/type-api.yaml index 80f7aa89dc..995f898d2f 100644 --- a/etc/api/type-api.yaml +++ b/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 diff --git a/src/mako/cli/lib/argparse.mako b/src/mako/cli/lib/argparse.mako index 46656d4d27..6e14ce5c0b 100644 --- a/src/mako/cli/lib/argparse.mako +++ b/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 diff --git a/src/mako/deps.mako b/src/mako/deps.mako index 14584a112e..77b8987b0b 100644 --- a/src/mako/deps.mako +++ b/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. diff --git a/src/mako/index.html.mako b/src/mako/index.html.mako index 3184bd4e23..4b46e7cf19 100644 --- a/src/mako/index.html.mako +++ b/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 ${an} ${v} ( % for program_type in type_names: - <% ad = tc[program_type] %> - ${ad.make.id.upper()} + <% + ad = tc[program_type] + revision = api_data.get('revision', None) + %>\ + ${ad.make.id.upper()} % if program_type == 'api': - + % else: - , + , % endif % if not loop.last: , diff --git a/src/mako/lib/util.mako b/src/mako/lib/util.mako index e277b9724d..de1b9e8268 100644 --- a/src/mako/lib/util.mako +++ b/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 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)}\ ## All crates and standard `use` declaration, required for all examples diff --git a/src/mako/lib/util.py b/src/mako/lib/util.py index 323d3503a4..0e9c64dca2 100644 --- a/src/mako/lib/util.py +++ b/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):