Add support for additional EXAMPLES string in Ansible modules

return DOC and EXAMPLES as a list
add moduledev explanation
more
This commit is contained in:
Jan-Piet Mens 2013-02-18 15:31:38 +01:00
parent 093935ede1
commit 396a07bcc7
7 changed files with 50 additions and 7 deletions

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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