From 405c097c43fbc9684eed3ac71499177567c08924 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Thu, 27 Sep 2012 21:30:32 -0400 Subject: [PATCH] Various fixes for the module documentation auto-generator --- hacking/module_formatter.py | 101 ++++++++++++++++++------------------ hacking/templates/rst.j2 | 11 +++- library/get_url | 2 +- library/ini_file | 5 +- 4 files changed, 64 insertions(+), 55 deletions(-) diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index e3a691d655..2cc40581d0 100755 --- a/hacking/module_formatter.py +++ b/hacking/module_formatter.py @@ -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(): @@ -242,10 +243,10 @@ 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() diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index ac193cb9a5..74701bbfca 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -41,4 +41,13 @@ {% endif %} - FIXME: include the examples here! +.. raw:: html + +{% for example in examples %} +

@{ example['description'] }@

+ 

+    @{ example['code'] }@

+{% endfor %} +
+ + diff --git a/library/get_url b/library/get_url index 68d9d8ccb7..426d0f1c9c 100755 --- a/library/get_url +++ b/library/get_url @@ -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. diff --git a/library/ini_file b/library/ini_file index 0a640b231f..7f1d93372c 100755 --- a/library/ini_file +++ b/library/ini_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