From 35ec9f81ae567dadc0947d962b95a0f61904a938 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Wed, 25 Dec 2013 13:23:58 -0500 Subject: [PATCH] Further modifications to the module formatter to adjust to the new theme, and some misc docs text corrections. --- .gitignore | 4 +- docsite/Makefile | 2 +- docsite/rst/developing_modules.rst | 18 ++++----- docsite/rst/index.rst | 3 +- docsite/rst/modules.rst | 61 ++++++------------------------ hacking/module_formatter.py | 38 ++++++++++++++++--- 6 files changed, 58 insertions(+), 68 deletions(-) diff --git a/.gitignore b/.gitignore index 3d33ca7a3a1..52039a3033c 100644 --- a/.gitignore +++ b/.gitignore @@ -24,7 +24,9 @@ docs/man/man3/* *.sublime-project *.sublime-workspace # docsite stuff... -docsite/rst/modules +docsite/rst/modules_by_category.rst +docsite/rst/list_of_*.rst +docsite/rst/*_module.rst docsite/*.html docsite/_static/*.gif docsite/_static/*.png diff --git a/docsite/Makefile b/docsite/Makefile index 39b3cc647ee..f31fd3d58f3 100644 --- a/docsite/Makefile +++ b/docsite/Makefile @@ -27,6 +27,6 @@ clean: .PHONEY: docs clean modules: $(FORMATTER) ../hacking/templates/rst.j2 - PYTHONPATH=../lib $(FORMATTER) -t rst --template-dir=../hacking/templates --module-dir=../library -o rst/modules/ --includes-file=rst/modules/_categories.rst + PYTHONPATH=../lib $(FORMATTER) -t rst --template-dir=../hacking/templates --module-dir=../library -o rst/ diff --git a/docsite/rst/developing_modules.rst b/docsite/rst/developing_modules.rst index 1d5e9e4f814..342dcba23bf 100644 --- a/docsite/rst/developing_modules.rst +++ b/docsite/rst/developing_modules.rst @@ -226,8 +226,7 @@ The 'group' and 'user' modules are reasonably non-trivial and showcase what this Key parts include always ending the module file with:: - # include magic from lib/ansible/module_common.py - #<> + from ansible.module_utils.basic import * main() And instantiating the module class like:: @@ -372,10 +371,7 @@ syntax highlighting before you include it in your Python file. Example +++++++ -To print a basic documentation string, run ``./hacking/module_formatter.py -G``. - -You can copy it into your module and use it as a starting point -when writing your own docs. +See an example documentation string in the checkout under examples/DOCUMENTATION.yml Include it in your module file like this:: @@ -389,8 +385,9 @@ Include it in your module file like this:: # ... snip ... ''' -The ``description``, and ``notes`` -support formatting in some of the output formats (e.g. ``rst``, ``man``). +The ``description``, and ``notes`` fields +support formatting with some special macros. + These formatting functions are ``U()``, ``M()``, ``I()``, and ``C()`` for URL, module, italic, and constant-width respectively. It is suggested to use ``C()`` for file and option names, and ``I()`` when referencing @@ -405,9 +402,8 @@ like this:: - action: modulename opt1=arg1 opt2=arg2 ''' -The ``module_formatter.py`` script and ``ansible-doc(1)`` append the -``EXAMPLES`` blob after any existing (deprecated) ``examples`` you may have in the -YAML ``DOCUMENTATION`` string. +The EXAMPLES section, just like the documentation section, is required in +all module pull requests for new modules. .. _module_dev_testing: diff --git a/docsite/rst/index.rst b/docsite/rst/index.rst index 68e96d59bbd..864cd337969 100644 --- a/docsite/rst/index.rst +++ b/docsite/rst/index.rst @@ -23,12 +23,13 @@ This documentation covers the current released version of Ansible (1.4.3) and al .. _an_introduction: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 intro playbooks playbooks_special_topics modules + modules_by_category guides developing awx diff --git a/docsite/rst/modules.rst b/docsite/rst/modules.rst index 3348d2b8043..3818800a12a 100644 --- a/docsite/rst/modules.rst +++ b/docsite/rst/modules.rst @@ -1,5 +1,5 @@ -Ansible Modules -=============== +About Modules +============= .. toctree:: :maxdepth: 4 @@ -9,11 +9,10 @@ Ansible Modules Introduction ```````````` - Ansible ships with a number of modules (called the 'module library') that can be executed directly on remote hosts or through :doc:`Playbooks `. -Users can also write their own modules. These modules can control system -resources, like services, packages, or files (anything really), or + +Users can also write their own modules. These modules can control system resources, like services, packages, or files (anything really), or handle executing system commands. Let's review how we execute three different modules from the command line:: @@ -23,64 +22,28 @@ Let's review how we execute three different modules from the command line:: ansible webservers -m command -a "/sbin/reboot -t now" Each module supports taking arguments. Nearly all modules take ``key=value`` -arguments, space delimited. Some modules take no arguments, and the -command/shell modules simply take the string of the command you want to run. +arguments, space delimited. Some modules take no arguments, and the command/shell modules simply +take the string of the command you want to run. From playbooks, Ansible modules are executed in a very similar way:: - name: reboot the servers action: command /sbin/reboot -t now -Version 0.8 and higher support the following shorter syntax:: +Which can be abbreviated to: - name: reboot the servers command: /sbin/reboot -t now -All modules technically return JSON format data, though if you are using the -command line or playbooks, you don't really need to know much about -that. If you're writing your own module, you care, and this means you do -not have to write modules in any particular language -- you get to choose. +All modules technically return JSON format data, though if you are using the command line or playbooks, you don't really need to know much about +that. If you're writing your own module, you care, and this means you do not have to write modules in any particular language -- you get to choose. Modules are `idempotent`, meaning they will seek to avoid changes to the system unless a change needs to be made. When using Ansible -playbooks, these modules can trigger 'change events' in the form of notifying 'handlers' -to run additional tasks. +playbooks, these modules can trigger 'change events' in the form of notifying 'handlers' to run additional tasks. -Documentation for each module can be accessed from the command line with the -ansible-doc as well as the man command:: +Documentation for each module can be accessed from the command line with the ansible-doc tool:: - ansible-doc command - - man ansible.template - -Let's see what's available in the Ansible module library, out of the box: - -.. include:: modules/_categories.rst - -.. _ansible_doc: - -Reading Module Documentation Locally -```````````````````````````````````` - -ansible-doc is a friendly command line tool that allows you to access module documentation locally. -It comes with Ansible. - -To list documentation for a particular module:: - - ansible-doc yum | less - -To list all modules available:: - - ansible-doc --list | less - -To access modules outside of the stock module path (such as custom modules that live in your playbook directory), -use the '--module-path' option to specify the directory where the module lives. - -.. _writing_modules: - -Writing your own modules -```````````````````````` - -See :doc:`developing_modules`. + ansible-doc yum .. seealso:: diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index f6ab8d596ac..787bf4e2d27 100755 --- a/hacking/module_formatter.py +++ b/hacking/module_formatter.py @@ -102,7 +102,7 @@ def rst_xline(width, char="="): ##################################################################################### -def return_data(text, options, outputname, module): +def write_data(text, options, outputname, module): ''' dumps module output to a file or the screen, as requested ''' if options.output_dir is not None: @@ -188,7 +188,7 @@ def jinja2_environment(template_dir, typ): env.filters['fmt'] = rst_fmt env.filters['xline'] = rst_xline template = env.get_template('rst.j2') - outputname = "%s.rst" + outputname = "%s_module.rst" else: raise Exception("unknown module format type: %s" % typ) @@ -214,7 +214,7 @@ def process_module(module, options, env, template, outputname, module_map): sys.stderr.write("*** ERROR: CORE MODULE MISSING DOCUMENTATION: %s, %s ***\n" % (fname, module)) sys.exit(1) if doc is None: - return + return "SKIPPED" all_keys = [] @@ -250,7 +250,7 @@ def process_module(module, options, env, template, outputname, module_map): # here is where we build the table of contents... text = template.render(doc) - return_data(text, options, outputname, module) + write_data(text, options, outputname, module) ##################################################################################### @@ -258,6 +258,10 @@ def process_category(category, categories, options, env, template, outputname): module_map = categories[category] + category_file_path = os.path.join(options.output_dir, "list_of_%s_modules.rst" % category) + category_file = open(category_file_path, "w") + print "*** recording category %s in %s ***" % (category, category_file_path) + # TODO: start a new category file category = category.replace("_"," ") @@ -266,8 +270,22 @@ def process_category(category, categories, options, env, template, outputname): modules = module_map.keys() modules.sort() + category_header = "%s Modules" % (category.title()) + underscores = "`" * len(category_header) + + category_file.write(category_header) + category_file.write("\n") + category_file.write(underscores) + category_file.write("\n") + category_file.write(".. toctree::\n") + for module in modules: - process_module(module, options, env, template, outputname, module_map) + result = process_module(module, options, env, template, outputname, module_map) + if result != "SKIPPED": + category_file.write(" %s_module\n" % module) + + + category_file.close() # TODO: end a new category file @@ -305,9 +323,19 @@ def main(): last_category = None category_names = categories.keys() category_names.sort() + + category_list_path = os.path.join(options.output_dir, "modules_by_category.rst") + category_list_file = open(category_list_path, "w") + category_list_file.write("Module Index\n") + category_list_file.write("============\n") + category_list_file.write("\n\n") + category_list_file.write(".. toctree::\n") for category in category_names: + category_list_file.write(" list_of_%s_modules\n" % category) process_category(category, categories, options, env, template, outputname) + category_list_file.close() + if __name__ == '__main__': main()