From 7681b1ce68369f1c21eaa621ddedde20d782896d Mon Sep 17 00:00:00 2001 From: Dale Sedivec 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("" + r"\1" + "", text) + t = cgi.escape(text) + t = _ITALIC.sub("" + r"\1" + "", t) t = _BOLD.sub("" + r"\1" + "", t) t = _MODULE.sub("" + r"\1" + "", t) t = _URL.sub("" + r"\1" + "", t) t = _CONST.sub("" + r"\1" + "", 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 }@. {% endif %} +{% if examples or plainexamples %} +#### Examples +{% endif %} + {% for example in examples %} {% if example['description'] %} * @{ example['description'] | jpfunc }@