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.
pull/3220/head
Dale Sedivec 12 years ago
parent cf2ddb6f80
commit 7681b1ce68

@ -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)

@ -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 }@

Loading…
Cancel
Save