Markdown format updates (#8)

- Fix syntax error in markdown template
- Only convert text to markdown if html format is being used
- Add a few blank lines for markdown
- Update the overview section so it uses markdown instead of html

Author: guymers

.gitignore

@@ -0,0 +1 @@
+bazel-*

skydoc/main.py

@@ -17,6 +17,7 @@
 
 import gflags
 import jinja2
+import mistune
 import os
 import re
 import shutil
@@ -54,6 +55,14 @@
 CSS_FILE = 'main.css'
 CSS_DIR = 'css'
 
+def _create_jinja_environment():
+  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))
+  return env
+
 
 # TODO(dzc): Remove this workaround once we switch to a self-contained Python
 # binary format such as PEX.
@@ -135,9 +144,7 @@ def write(self, rulesets):
 
   def _write_ruleset(self, output_dir, ruleset):
     # Load template and render Markdown.
-    env = jinja2.Environment(
-        loader=jinja2.FileSystemLoader(_runfile_path(TEMPLATE_PATH)),
-        line_statement_prefix='%')
+    env = _create_jinja_environment()
     template = env.get_template('markdown.jinja')
     out = template.render(ruleset=ruleset)
 
@@ -154,9 +161,7 @@ def __init__(self, output_dir, output_file, output_zip):
     self.__output_dir = output_dir
     self.__output_file = output_file
     self.__output_zip = output_zip
-    self.__env = jinja2.Environment(
-        loader=jinja2.FileSystemLoader(_runfile_path(TEMPLATE_PATH)),
-        line_statement_prefix='%')
+    self.__env = _create_jinja_environment()
 
   def write(self, rulesets):
     # Generate navigation used for all rules.

skydoc/rule.py

@@ -15,7 +15,6 @@
 """Representations used for rendering documentation templates."""
 
 
-import mistune
 from skydoc import build_pb2
 
 
@@ -34,7 +33,7 @@ def __init__(self, proto):
     if proto.name == 'name' and not proto.documentation:
       self.documentation = 'A unique name for this rule.'
     else:
-      self.documentation = mistune.markdown(proto.documentation)
+      self.documentation = proto.documentation
 
   def _get_type_str(self, proto):
     type_str = ''
@@ -90,17 +89,17 @@ class Output(object):
 
   def __init__(self, proto):
     self.__proto = proto
-    self.template = mistune.markdown(proto.template)
-    self.documentation = mistune.markdown(proto.documentation)
+    self.template = proto.template
+    self.documentation = proto.documentation
 
 class Rule(object):
   """Representation of a rule used to render documentation templates."""
 
   def __init__(self, proto):
     self.__proto = proto
     self.name = proto.name
-    self.documentation = mistune.markdown(proto.documentation)
-    self.example_documentation = mistune.markdown(proto.example_documentation)
+    self.documentation = proto.documentation
+    self.example_documentation = proto.example_documentation
     self.signature = self._get_signature(proto)
     self.attributes = []
     for attribute in proto.attribute:

skydoc/templates/BUILD

@@ -8,7 +8,6 @@ filegroup(
         "markdown.jinja",
         "nav.jinja",
         "outputs.jinja",
-        "overview.jinja",
         "toc.jinja",
     ],
 )

skydoc/templates/attributes.jinja

@@ -24,7 +24,7 @@ limitations under the License.
       <td><code>{{ attribute.name }}</code></td>
       <td>
         <p><code>{{ attribute.type }}</code></p>
-        {{ attribute.documentation }}
+        {{ attribute.documentation|markdown|trim }}
       </td>
     </tr>
 % endfor

skydoc/templates/html.jinja

@@ -52,15 +52,19 @@ Documentation generated by Skydoc
         <div class="page-content">
           <h1>{{ ruleset.title }}</h1>
 % include "toc.jinja"
-% include "overview.jinja"
+% if ruleset.description:
+          <hr>
+          <h2 id="overview">Overview<h2>
+          {{ ruleset.description|markdown }}
+% endif
 % for rule in ruleset.rules
           <hr>
 
           <h2 id="{{ rule.name }}">{{ rule.name }}</h2>
 
           <pre>{{ rule.signature }}</pre>
 
-          {{ rule.documentation }}
+          {{ rule.documentation|markdown }}
 
 % if rule.outputs[0] is defined:
           <h3 id="{{ rule.name }}_outputs">
@@ -76,7 +80,7 @@ Documentation generated by Skydoc
 
 % if rule.example_documentation
           <h3 id="{{ rule.name }}_examples">Examples</h3>
-          {{ rule.example_documentation }}
+          {{ rule.example_documentation|markdown }}
 % endif
 
 % endfor

skydoc/templates/markdown.jinja

@@ -19,7 +19,16 @@ Documentation generated by Skydoc
 <h1>{{ ruleset.title }}</h1>
 
 % include "toc.jinja"
-% include "overview.jinja"
+
+% if ruleset.description:
+<hr>
+
+<a name="overview"></a>
+## Overview
+
+{{ ruleset.description }}
+{# I want a blank line here #}
+% endif
 
 % for rule in ruleset.rules:
 <a name="{{ rule.name }}"></a>
@@ -32,20 +41,23 @@ Documentation generated by Skydoc
 {{ rule.documentation }}
 
 % if rule.outputs[0] is defined:
+{# I want a blank line here #}
 <a name="{{ rule.name }}_outputs"></a>
 ### Outputs
 
 % include "outputs.jinja"
 % endif
 
 % if rule.attributes[0] is defined:
+{# I want a blank line here #}
 <a name="{{ rule.name }}_args"></a>
 ### Attributes
 
 % include "attributes.jinja"
 % endif
 
 % if rule.example_documentation
+{# I want a blank line here #}
 <a name="{{ rule.name }}_examples"></a>
 ### Examples
 

skydoc/templates/outputs.jinja

@@ -23,7 +23,7 @@ limitations under the License.
     <tr>
       <td><code>{{ output.template }}</code></td>
       <td>
-        {{ output.documentation }}
+        {{ output.documentation|markdown|trim }}
       </td>
     </tr>
 % endfor