Add site_root attribute for specifying site root url to prepend links. (

#42)
bazelbuild · Feb 13, 2017 · 7dd0264 · 7dd0264
1 parent 3c6a103
commit 7dd0264
Show file tree

Hide file tree

Showing 5 changed files with 36 additions and 16 deletions.
diff --git 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,20 +125,25 @@ 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
     self.overview = 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
@@ -29,7 +29,7 @@ Documentation generated by Skydoc
     <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
     <link rel="stylesheet" href="https://code.getmdl.io/1.1.1/material.green-light_blue.min.css">
     <script defer src="https://code.getmdl.io/1.1.1/material.min.js"></script>
-    <link rel="stylesheet" href="/main.css">
+    <link rel="stylesheet" href="{{ 'main.css' | link }}">
   </head>
   <body>
     <div class="mdl-layout mdl-js-layout mdl-layout--fixed-drawer

diff --git a/skydoc/templates/nav.jinja b/skydoc/templates/nav.jinja
@@ -15,17 +15,17 @@ limitations under the License.
 #}
 % for ruleset in rulesets:
 % if overview:
-<li><a href="{{ overview_filename | link }}">Overview</a></li>
+<li><a href="{{ overview_filename | doc_link }}">Overview</a></li>
 % endif
 <li>
-  <a href="{{ ruleset.output_file | link }}">{{ ruleset.title }}</a>
+  <a href="{{ ruleset.output_file | doc_link }}">{{ ruleset.title }}</a>
   <ul>
 % if ruleset.description:
-    <li><a href="{{ ruleset.output_file | link }}#overview">Overview</a></li>
+    <li><a href="{{ ruleset.output_file | doc_link }}#overview">Overview</a></li>
 % endif
 % for rule in ruleset.rules:
     <li>
-      <a href="{{ ruleset.output_file | link }}#{{ rule.name }}">
+      <a href="{{ ruleset.output_file | doc_link }}#{{ rule.name }}">
         {{ rule.name }}
       </a>
     </li>

diff --git a/skydoc/templates/overview.jinja b/skydoc/templates/overview.jinja
@@ -23,7 +23,7 @@ limitations under the License.
 </nav>
 
 % for ruleset in rulesets:
-<h2><a href="{{ ruleset.output_file | link }}">{{ ruleset.title }}</a></h2>
+<h2><a href="{{ ruleset.output_file | doc_link }}">{{ ruleset.title }}</a></h2>
 
 % if ruleset.rules[0] is defined:
 <h3>Rules</h3>
@@ -36,7 +36,7 @@ limitations under the License.
 % for rule in ruleset.rules:
     <tr>
       <td>
-        <a href="{{ ruleset.output_file | link }}#{{ rule.name }}">
+        <a href="{{ ruleset.output_file | doc_link }}#{{ rule.name }}">
           <code>{{ rule.name }}</code>
         </a>
       </td>
@@ -60,7 +60,7 @@ limitations under the License.
 % for rule in ruleset.macros:
     <tr>
       <td>
-        <a href="{{ ruleset.output_file | link }}#{{ rule.name }}">
+        <a href="{{ ruleset.output_file | doc_link }}#{{ rule.name }}">
           <code>{{ rule.name }}</code>
         </a>
       </td>
@@ -84,7 +84,7 @@ limitations under the License.
 % for rule in ruleset.repository_rules:
     <tr>
       <td>
-        <a href="{{ ruleset.output_file | link }}#{{ rule.name }}">
+        <a href="{{ ruleset.output_file | doc_link }}#{{ rule.name }}">
           <code>{{ rule.name }}</code>
         </a>
       </td>

diff --git 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.