From 7681b1ce68369f1c21eaa621ddedde20d782896d Mon Sep 17 00:00:00 2001
From: Dale Sedivec <dale@codefu.org>
Date: Fri, 14 Jun 2013 13:27:59 -0500
Subject: [PATCH] Improve Markdown (and other) module doc output

- The html_ify filter now escapes HTML found in module documentation.
  THIS COULD AFFECT MORE THAN JUST MARKDOWN but I didn't see any modules
  expecting to use e.g. HTML entities or HTML tags in their
  documentation.

- The markdown_ify filter (used as jpfunc in markdown.j2) escapes at
  least a few Markdown in-line formatting characters.

- Improvements to markdown.j2:

    - Call jpfunc on the module name heading so that it gets escaped for
      Markdown (e.g. my_module_name becomes my\_module\_name).

    - Added paragraph breaks between paragraphs in the description.

    - Added examples heading, which is consistent with the notes heading
      below it.
---
 hacking/module_formatter.py   | 11 +++++++++--
 hacking/templates/markdown.j2 |  9 +++++++--
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py
index 7eb1e106fbe..e16575676e7 100755
--- a/hacking/module_formatter.py
+++ b/hacking/module_formatter.py
@@ -30,6 +30,7 @@ import optparse
 import time
 import datetime
 import subprocess
+import cgi
 import ansible.utils
 import ansible.utils.module_docs as module_docs
 
@@ -62,11 +63,13 @@ def latex_ify(text):
 
 def html_ify(text):
 
-    t = _ITALIC.sub("<em>" + r"\1" + "</em>", text)
+    t = cgi.escape(text)
+    t = _ITALIC.sub("<em>" + r"\1" + "</em>", t)
     t = _BOLD.sub("<b>" + r"\1" + "</b>", t)
     t = _MODULE.sub("<span class='module'>" + r"\1" + "</span>", t)
     t = _URL.sub("<a href='" + r"\1" + "'>" + r"\1" + "</a>", t)
     t = _CONST.sub("<code>" + r"\1" + "</code>", t)
+
     return t
 
 def json_ify(text):
@@ -105,9 +108,13 @@ def rst_ify(text):
 
     return t
 
+_MARKDOWN = re.compile(r"[*_`]")
+
 def markdown_ify(text):
 
-    t = _ITALIC.sub("_" + r"\1" + "_", text)
+    t = cgi.escape(text)
+    t = _MARKDOWN.sub(r"\\\g<0>", t)
+    t = _ITALIC.sub("_" + r"\1" + "_", t)
     t = _BOLD.sub("**" + r"\1" + "**", t)
     t = _MODULE.sub("*" + r"\1" + "*", t)
     t = _URL.sub("[" + r"\1" + "](" + r"\1" + ")", t)
diff --git a/hacking/templates/markdown.j2 b/hacking/templates/markdown.j2
index 0cc8151fde9..6f9bb0b3d88 100644
--- a/hacking/templates/markdown.j2
+++ b/hacking/templates/markdown.j2
@@ -1,4 +1,4 @@
-## @{ module }@
+## @{ module | jpfunc }@
 
 {# ------------------------------------------
  #
@@ -11,7 +11,8 @@ New in version @{ version_added }@.
 {% endif %}
 
 {% for desc in description -%}
-@{ desc | jpfunc }@ 
+@{ desc | jpfunc }@
+
 {% endfor %}
 
 {% if options -%}
@@ -35,6 +36,10 @@ New in version @{ version_added }@.
 </table>
 {% endif %}
 
+{% if examples or plainexamples %}
+#### Examples
+{% endif %}
+
 {% for example in examples %}
 {% if example['description'] %}
 * @{ example['description'] | jpfunc }@