From 396a07bcc7d5aa3f6a345bb10620e4a8cab82cb0 Mon Sep 17 00:00:00 2001 From: Jan-Piet Mens Date: Mon, 18 Feb 2013 15:31:38 +0100 Subject: [PATCH] Add support for additional EXAMPLES string in Ansible modules return DOC and EXAMPLES as a list add moduledev explanation more --- bin/ansible-doc | 8 ++++++-- docsite/rst/moduledev.rst | 13 +++++++++++++ hacking/module_formatter.py | 3 ++- hacking/templates/man.j2 | 7 +++++++ hacking/templates/markdown.j2 | 6 +++++- hacking/templates/rst.j2 | 8 ++++++++ lib/ansible/utils/module_docs.py | 12 +++++++++--- 7 files changed, 50 insertions(+), 7 deletions(-) diff --git a/bin/ansible-doc b/bin/ansible-doc index cf75f07e44..c1d3243de0 100755 --- a/bin/ansible-doc +++ b/bin/ansible-doc @@ -91,6 +91,9 @@ def print_man(doc): for ex in doc['examples']: print "%s\n" % (ex['code']) + if 'plainexamples' in doc and doc['plainexamples'] is not None: + print doc['plainexamples'] + def print_snippet(doc): desc = tty_ify("".join(doc['short_description'])) @@ -153,7 +156,7 @@ def main(): filename = utils.plugins.module_finder.find_plugin(module) try: - doc = module_docs.get_docstring(filename) + doc, plainexamples = module_docs.get_docstring(filename) desc = tty_ify(doc.get('short_description', '?')) if len(desc) > 55: desc = desc + '...' @@ -180,7 +183,7 @@ def main(): continue try: - doc = module_docs.get_docstring(filename) + doc, plainexamples = module_docs.get_docstring(filename) except: traceback.print_exc() sys.stderr.write("ERROR: module %s has a documentation error formatting or is missing documentation\n" % module) @@ -197,6 +200,7 @@ def main(): doc['filename'] = filename doc['docuri'] = doc['module'].replace('_', '-') doc['now_date'] = datetime.date.today().strftime('%Y-%m-%d') + doc['plainexamples'] = plainexamples if options.show_snippet: print_snippet(doc) diff --git a/docsite/rst/moduledev.rst b/docsite/rst/moduledev.rst index bd13d04aa3..223a556c8c 100644 --- a/docsite/rst/moduledev.rst +++ b/docsite/rst/moduledev.rst @@ -354,6 +354,19 @@ for URL, module, italic, and constant-width respectively. It is suggested to use ``C()`` for file and option names, and ``I()`` when referencing parameters; module names should be specifies as ``M(module)``. +Examples (which typically contain colons, quotes, etc.) are difficult +to format with YAML, so these can (alternatively, or additionally) be +written in plain text in an ``EXAMPLES`` string within the module +like this:: + + EXAMPLES = ''' + - action: modulename opt1=arg1 opt2=arg2 + ''' + +The ``module_formatter.py`` script and ``ansible-doc(1)`` append the +``EXAMPLES`` blob after any existing ``examples`` you may have in the +YAML ``DOCUMENTATION`` string. + Building & Testing ++++++++++++++++++ diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index 71e8777a43..eb87e500c9 100755 --- a/hacking/module_formatter.py +++ b/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) diff --git a/hacking/templates/man.j2 b/hacking/templates/man.j2 index 36764bd4e0..90e429742b 100644 --- a/hacking/templates/man.j2 +++ b/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 diff --git a/hacking/templates/markdown.j2 b/hacking/templates/markdown.j2 index 2c65af0fa3..0cc8151fde 100644 --- a/hacking/templates/markdown.j2 +++ b/hacking/templates/markdown.j2 @@ -44,7 +44,11 @@ New in version @{ version_added }@. @{ example['code'] }@ ``` {% endfor %} - +{% if plainexamples -%} +``` +@{ plainexamples }@ +``` +{% endif %} {% if notes %} #### Notes diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index a619f6a298..5952581426 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -54,6 +54,14 @@ {% endfor %}
+{% if plainexamples %} +.. raw:: html + + 
+@{ plainexamples | escape | indent(4, True) }@
+
+{% endif %} + {% if notes %} .. raw:: html diff --git a/lib/ansible/utils/module_docs.py b/lib/ansible/utils/module_docs.py index 221cb4ad4e..e8e5541716 100755 --- a/lib/ansible/utils/module_docs.py +++ b/lib/ansible/utils/module_docs.py @@ -30,11 +30,14 @@ BLACKLIST_MODULES = [ def get_docstring(filename, verbose=False): """ - Search for assignment of the DOCUMENTATION variable in the given file. - Parse that from YAML and return the YAML doc or None. + Search for assignment of the DOCUMENTATION and EXAMPLES variables + in the given file. + Parse DOCUMENTATION from YAML and return the YAML doc or None + together with EXAMPLES, as plain text. """ doc = None + plainexamples = None try: # Thank you, Habbie, for this bit of code :-) @@ -43,8 +46,11 @@ def get_docstring(filename, verbose=False): if isinstance(child, ast.Assign): if 'DOCUMENTATION' in (t.id for t in child.targets): doc = yaml.load(child.value.s) + if 'EXAMPLES' in (t.id for t in child.targets): + plainexamples = child.value.s[1:] # Skip first empty line except: if verbose == True: traceback.print_exc() print "unable to parse %s" % filename - return doc + return doc, plainexamples +