Merge pull request #2120 from jpmens/doc_ex1

Add support for additional EXAMPLES string in Ansible modules

hacking/module_formatter.py

@@ -296,7 +296,7 @@ def main():
                 js_data.append(j)
             continue
 
-        doc = ansible.utils.module_docs.get_docstring(fname, verbose=options.verbose)
+        doc, examples = ansible.utils.module_docs.get_docstring(fname, verbose=options.verbose)
 
         if doc is None and module not in ansible.utils.module_docs.BLACKLIST_MODULES:
             sys.stderr.write("*** ERROR: CORE MODULE MISSING DOCUMENTATION: %s ***\n" % module)
@@ -314,6 +314,7 @@ def main():
             doc['docuri']           = doc['module'].replace('_', '-')
             doc['now_date']         = datetime.date.today().strftime('%Y-%m-%d')
             doc['ansible_version']  = options.ansible_version
+            doc['plainexamples']    = examples  #plain text
 
             if options.includes_file is not None and includefmt != "":
                 incfile.write(includefmt % module)

hacking/templates/man.j2

@@ -56,6 +56,13 @@
 .fi
 {% endfor %}
 {% endif %}
+." ------ PLAINEXAMPLES
+{% if plainexamples is defined %}
+.nf
+@{ plainexamples }@
+.fi
+{% endif %}
+
 ." ------- AUTHOR
 {% if author is defined %}
 .SH AUTHOR

hacking/templates/markdown.j2

@@ -44,7 +44,11 @@ New in version @{ version_added }@.
 @{ example['code'] }@
 ```
 {% endfor %}
- 
+{% if plainexamples -%}
+```
+@{ plainexamples }@
+```
+{% endif %}
 
 {% if notes %}
 #### Notes

hacking/templates/rst.j2

@@ -54,6 +54,14 @@
 {% endfor %}
     <br/>
 
+{% if plainexamples %}
+.. raw:: html
+
+    <pre>
+@{ plainexamples | escape | indent(4, True) }@
+    </pre>
+{% endif %}
+
 {% if notes %}
 .. raw:: html