From 8b851dba7810b5f3bd62c58ab25f9f058ebc1a9e Mon Sep 17 00:00:00 2001
From: Sam Guymer <sam@guymer.me>
Date: Thu, 16 Jun 2016 16:23:51 +1000
Subject: [PATCH] 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
---
 .gitignore                        |  1 +
 skydoc/main.py                    | 17 +++++++++++------
 skydoc/rule.py                    | 11 +++++------
 skydoc/templates/BUILD            |  1 -
 skydoc/templates/attributes.jinja |  2 +-
 skydoc/templates/html.jinja       | 10 +++++++---
 skydoc/templates/markdown.jinja   | 14 +++++++++++++-
 skydoc/templates/outputs.jinja    |  2 +-
 skydoc/templates/overview.jinja   | 22 ----------------------
 9 files changed, 39 insertions(+), 41 deletions(-)
 create mode 100644 .gitignore
 delete mode 100644 skydoc/templates/overview.jinja

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..ac51a05
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+bazel-*
diff --git a/skydoc/main.py b/skydoc/main.py
index 511bded..b32f230 100755
--- a/skydoc/main.py
+++ b/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.
diff --git a/skydoc/rule.py b/skydoc/rule.py
index b7b7657..e6b4bb6 100644
--- a/skydoc/rule.py
+++ b/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,8 +89,8 @@ 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."""
@@ -99,8 +98,8 @@ class Rule(object):
   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:
diff --git a/skydoc/templates/BUILD b/skydoc/templates/BUILD
index 72a2b6f..cac03e2 100644
--- a/skydoc/templates/BUILD
+++ b/skydoc/templates/BUILD
@@ -8,7 +8,6 @@ filegroup(
         "markdown.jinja",
         "nav.jinja",
         "outputs.jinja",
-        "overview.jinja",
         "toc.jinja",
     ],
 )
diff --git a/skydoc/templates/attributes.jinja b/skydoc/templates/attributes.jinja
index d9acf13..6d58577 100644
--- a/skydoc/templates/attributes.jinja
+++ b/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
diff --git a/skydoc/templates/html.jinja b/skydoc/templates/html.jinja
index c96bfaf..c156f88 100644
--- a/skydoc/templates/html.jinja
+++ b/skydoc/templates/html.jinja
@@ -52,7 +52,11 @@ 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>
 
@@ -60,7 +64,7 @@ Documentation generated by Skydoc
 
           <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
diff --git a/skydoc/templates/markdown.jinja b/skydoc/templates/markdown.jinja
index 2233a59..c912da8 100644
--- a/skydoc/templates/markdown.jinja
+++ b/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,6 +41,7 @@ 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
 
@@ -39,6 +49,7 @@ Documentation generated by Skydoc
 % endif
 
 % if rule.attributes[0] is defined:
+{# I want a blank line here #}
 <a name="{{ rule.name }}_args"></a>
 ### Attributes
 
@@ -46,6 +57,7 @@ Documentation generated by Skydoc
 % endif
 
 % if rule.example_documentation
+{# I want a blank line here #}
 <a name="{{ rule.name }}_examples"></a>
 ### Examples
 
diff --git a/skydoc/templates/outputs.jinja b/skydoc/templates/outputs.jinja
index a620c0d..68a3c19 100644
--- a/skydoc/templates/outputs.jinja
+++ b/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
diff --git a/skydoc/templates/overview.jinja b/skydoc/templates/overview.jinja
deleted file mode 100644
index c0e47ea..0000000
--- a/skydoc/templates/overview.jinja
+++ /dev/null
@@ -1,22 +0,0 @@
-{#
-Copyright 2016 The Bazel Authors. All rights reserved.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-#}
-% if ruleset.description:
-<hr>
-
-<h2 id="overview">Overview<h2>
-
-{{ ruleset.description }}
-% endif