From 7dd02643a1c06ec6acce8a1f906808a89e52d1dd Mon Sep 17 00:00:00 2001 From: "David Z. Chen" Date: Mon, 13 Feb 2017 01:21:10 -0800 Subject: [PATCH] Add site_root attribute for specifying site root url to prepend links. (#42) --- skydoc/main.py | 23 ++++++++++++++++------- skydoc/templates/html_header.jinja | 2 +- skydoc/templates/nav.jinja | 8 ++++---- skydoc/templates/overview.jinja | 8 ++++---- skylark/skylark.bzl | 11 +++++++++++ 5 files changed, 36 insertions(+), 16 deletions(-) diff --git a/skydoc/main.py b/skydoc/main.py index 073b514..7fd5d5e 100755 --- a/skydoc/main.py +++ b/skydoc/main.py @@ -54,6 +54,8 @@ 'The file name to use for the overview page.') gflags.DEFINE_string('link_ext', 'html', 'The file extension used for links in the generated documentation') +gflags.DEFINE_string('site_root', '', + 'The site root to be prepended to all URLs in the generated documentation') FLAGS = gflags.FLAGS @@ -66,13 +68,15 @@ CSS_FILE = 'main.css' -def _create_jinja_environment(link_ext): +def _create_jinja_environment(site_root, link_ext): env = jinja2.Environment( loader=jinja2.FileSystemLoader(_runfile_path(TEMPLATE_PATH)), keep_trailing_newline=True, line_statement_prefix='%') env.filters['markdown'] = lambda text: jinja2.Markup(mistune.markdown(text)) - env.filters['link'] = lambda fname: '/' + fname + '.' + link_ext + env.filters['doc_link'] = ( + lambda fname: site_root + '/' + fname + '.' + link_ext) + env.filters['link'] = lambda fname: site_root + '/' + fname return env @@ -121,7 +125,7 @@ def merge_languages(macro_language, rule_language): class WriterOptions(object): def __init__(self, output_dir, output_file, output_zip, overview, - overview_filename, link_ext): + overview_filename, link_ext, site_root): self.output_dir = output_dir self.output_file = output_file self.output_zip = output_zip @@ -129,12 +133,17 @@ def __init__(self, output_dir, output_file, output_zip, overview, self.overview_filename = overview_filename self.link_ext = link_ext + self.site_root = site_root + if len(self.site_root) > 0 and self.site_root.endswith('/'): + self.site_root = self.site_root[:-1] + class MarkdownWriter(object): """Writer for generating documentation in Markdown.""" def __init__(self, writer_options): self.__options = writer_options - self.__env = _create_jinja_environment(self.__options.link_ext) + self.__env = _create_jinja_environment(self.__options.site_root, + self.__options.link_ext) def write(self, rulesets): """Write the documentation for the rules contained in rulesets.""" @@ -198,7 +207,8 @@ class HtmlWriter(object): def __init__(self, options): self.__options = options - self.__env = _create_jinja_environment(self.__options.link_ext) + self.__env = _create_jinja_environment(self.__options.site_root, + self.__options.link_ext) def write(self, rulesets): # Generate navigation used for all rules. @@ -302,10 +312,9 @@ def main(argv): rule.RuleSet(bzl_file, merged_language, macro_doc_extractor.title, macro_doc_extractor.description, strip_prefix, FLAGS.format)) - writer_options = WriterOptions( FLAGS.output_dir, FLAGS.output_file, FLAGS.zip, FLAGS.overview, - FLAGS.overview_filename, FLAGS.link_ext) + FLAGS.overview_filename, FLAGS.link_ext, FLAGS.site_root) if FLAGS.format == "markdown": markdown_writer = MarkdownWriter(writer_options) markdown_writer.write(rulesets) diff --git a/skydoc/templates/html_header.jinja b/skydoc/templates/html_header.jinja index 1d9d5fe..135bdc6 100644 --- a/skydoc/templates/html_header.jinja +++ b/skydoc/templates/html_header.jinja @@ -29,7 +29,7 @@ Documentation generated by Skydoc - +
Overview +
  • Overview
    • % endif
  • - {{ ruleset.title }} + {{ ruleset.title }}
      % if ruleset.description: -
    • Overview
      • +
    • Overview
      • % endif % for rule in ruleset.rules:
    • - + {{ rule.name }}
      • diff --git a/skydoc/templates/overview.jinja b/skydoc/templates/overview.jinja index 1386c7a..d4f61dc 100644 --- a/skydoc/templates/overview.jinja +++ b/skydoc/templates/overview.jinja @@ -23,7 +23,7 @@ limitations under the License. % for ruleset in rulesets: -

      {{ ruleset.title }}

      +

      {{ ruleset.title }}

      % if ruleset.rules[0] is defined:

      Rules

      @@ -36,7 +36,7 @@ limitations under the License. % for rule in ruleset.rules: - + {{ rule.name }} @@ -60,7 +60,7 @@ limitations under the License. % for rule in ruleset.macros: - + {{ rule.name }} @@ -84,7 +84,7 @@ limitations under the License. % for rule in ruleset.repository_rules: - + {{ rule.name }} diff --git a/skylark/skylark.bzl b/skylark/skylark.bzl index b852d29..86b0612 100644 --- a/skylark/skylark.bzl +++ b/skylark/skylark.bzl @@ -60,6 +60,8 @@ def _skylark_doc_impl(ctx): flags += ["--overview_filename=%s" % ctx.attr.overview_filename] if ctx.attr.link_ext: flags += ["--link_ext=%s" % ctx.attr.link_ext] + if ctx.attr.site_root: + flags += ["--site_root=%s" % ctx.attr.site_root] skydoc = _skydoc(ctx) ctx.action( inputs = list(inputs) + [skydoc], @@ -163,6 +165,7 @@ _skylark_doc_attrs = { "overview": attr.bool(default = True), "overview_filename": attr.string(), "link_ext": attr.string(), + "site_root": attr.string(), "skydoc": attr.label( default = Label("//skydoc"), cfg = "host", @@ -207,6 +210,14 @@ Args: respectively. link_ext: The file extension used for links in the generated documentation. By default, skydoc uses `.html`. + site_root: The site root to be prepended to all URLs in the generated + documentation, such as links, style sheets, and images. + + This is useful if the generated documentation is served from a subdirectory + on the web server. For example, if the skydoc site is to served from + `https://host.com/rules`, then by setting + `site_root = "https://host.com/rules"`, all links will be prefixed with + the site root, for example, `https://host.com/rules/index.html`. Outputs: skylark_doc_zip: A zip file containing the generated documentation.