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

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

hacking/templates/markdown.j2

@@ -1,4 +1,4 @@
-## @{ module }@
+## @{ module | jpfunc }@
 
 {# ------------------------------------------
  #
@@ -12,6 +12,7 @@ New in version @{ version_added }@.
 
 {% for desc in description -%}
 @{ 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 }@