1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00

Various fixes for the module documentation auto-generator

This commit is contained in:
Michael DeHaan 2012-09-27 21:30:32 -04:00
parent 83f277cfe6
commit 405c097c43
4 changed files with 64 additions and 55 deletions

View file

@ -45,23 +45,19 @@ description:
U(url) exists too.
version_added: "0.x"
options:
- dest:
required: true
description:
- What does this option do, and bla bla bla
- More than one paragraph allowed here as well. Formatting
with B(bold), etc. work too.
- remove:
required: false
choices: [ yes, no ]
default: "maybe"
aliases: [ kill, killme, delete ]
description:
- The foo to do on M(module) but be careful of lorem ipsum
examples:
- code: foo dest=/tmp/jj remove=maybe
description: Possibly removes the specified file
- code: foo dest=/dev/null
dest:
required: true
description:
- What does this option do, and bla bla bla
- More than one paragraph allowed here as well. Formatting
with B(bold), etc. work too.
remove:
required: false
choices: [ yes, no ]
default: "maybe"
aliases: [ kill, killme, delete ]
description:
- The foo to do on M(module) but be careful of lorem ipsum
'''
# There is a better way of doing this!
@ -128,6 +124,8 @@ env = Environment(loader=FileSystemLoader('../ansible/hacking/templates/'),
env.globals['xline'] = rst_xline
def load_examples_section(text):
return text.split('***BREAK***')
def get_docstring(filename, verbose=False):
"""
@ -144,10 +142,13 @@ 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)
except:
if verbose:
raise
pass
else:
print "unable to parse %s" % filename
return doc
def main():
@ -243,9 +244,9 @@ def main():
doc = get_docstring(fname, verbose=args.verbose)
if not doc is None:
doc['filename'] = fname
doc['docuri'] = doc['module'].replace('_', '-')
doc['now_date'] = datetime.date.today().strftime('%Y-%m-%d')
doc['filename'] = fname
doc['docuri'] = doc['module'].replace('_', '-')
doc['now_date'] = datetime.date.today().strftime('%Y-%m-%d')
doc['ansible_version'] = args.ansible_version
if args.verbose:
@ -267,34 +268,34 @@ def main():
else:
print text
def boilerplate():
# Sneaky: insert author's name from Git config
cmd = subprocess.Popen("git config --get user.name", shell=True,
stdout=subprocess.PIPE, stderr=subprocess.PIPE)
out, err = cmd.communicate()
if len(out.split('\n')) == 2:
author = out.split('\n')[0]
print author
else:
author = "Your Name"
# I can't dump YAML in ordered fasion, so I use this boilerplate string
# and verify it is parseable just before printing it out to the user.
try:
boilplate = yaml.load(BOILERPLATE)
except:
print "Something is wrong with the BOILERPLATE"
sys.exit(1)
print """
DOCUMENTATION = '''
%s
'''
"""[1:-1] % (BOILERPLATE.replace('AUTHORNAME', author) [1:-1] )
#def boilerplate():
#
# # Sneaky: insert author's name from Git config
#
# cmd = subprocess.Popen("git config --get user.name", shell=True,
# stdout=subprocess.PIPE, stderr=subprocess.PIPE)
# out, err = cmd.communicate()
#
# if len(out.split('\n')) == 2:
# author = out.split('\n')[0]
# print author
# else:
# author = "Your Name"
#
# # I can't dump YAML in ordered fasion, so I use this boilerplate string
# # and verify it is parseable just before printing it out to the user.
#
# try:
# boilplate = yaml.load(BOILERPLATE)
# except:
# print "Something is wrong with the BOILERPLATE"
# sys.exit(1)
#
# print """
#DOCUMENTATION = '''
#%s
#'''
#"""[1:-1] % (BOILERPLATE.replace('AUTHORNAME', author) [1:-1] )
if __name__ == '__main__':
main()

View file

@ -41,4 +41,13 @@
</table>
{% endif %}
FIXME: include the examples here!
.. raw:: html
{% for example in examples %}
<p>@{ example['description'] }@</p>
<p><pre>
@{ example['code'] }@</pre></p>
{% endfor %}
<br/>

View file

@ -61,7 +61,7 @@ options:
required: false
examples:
- code: get_url url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440
description: Obtain and install config file
description: "Example from Ansible Playbooks"
notes:
- This module doesn't support proxies or passwords.
- Also see the M(template) module.

View file

@ -34,7 +34,6 @@ options:
- Path to the INI-style file; this file is created if required
required: true
default: null
aliases: []
section:
description:
- Section name in INI file. This is added if C(state=present) automatically when
@ -46,12 +45,12 @@ options:
- if set (required for changing a I(value)), this is the name of the option.
- May be omitted if adding/removing a whole I(section).
required: false
default: []
default: null
value:
description:
- the string value to be associated with an I(option). May be omitted when removing an I(option).
required: false
default: []
default: null
backup:
description:
- Create a backup file including the timestamp information so you can get