Further modifications to the module formatter to adjust to the new theme, and some misc docs text corrections.
This commit is contained in:
parent
fe2d00d9d3
commit
35ec9f81ae
6 changed files with 58 additions and 68 deletions
4
.gitignore
vendored
4
.gitignore
vendored
|
@ -24,7 +24,9 @@ docs/man/man3/*
|
||||||
*.sublime-project
|
*.sublime-project
|
||||||
*.sublime-workspace
|
*.sublime-workspace
|
||||||
# docsite stuff...
|
# docsite stuff...
|
||||||
docsite/rst/modules
|
docsite/rst/modules_by_category.rst
|
||||||
|
docsite/rst/list_of_*.rst
|
||||||
|
docsite/rst/*_module.rst
|
||||||
docsite/*.html
|
docsite/*.html
|
||||||
docsite/_static/*.gif
|
docsite/_static/*.gif
|
||||||
docsite/_static/*.png
|
docsite/_static/*.png
|
||||||
|
|
|
@ -27,6 +27,6 @@ clean:
|
||||||
.PHONEY: docs clean
|
.PHONEY: docs clean
|
||||||
|
|
||||||
modules: $(FORMATTER) ../hacking/templates/rst.j2
|
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/
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -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::
|
Key parts include always ending the module file with::
|
||||||
|
|
||||||
# include magic from lib/ansible/module_common.py
|
from ansible.module_utils.basic import *
|
||||||
#<<INCLUDE_ANSIBLE_MODULE_COMMON>>
|
|
||||||
main()
|
main()
|
||||||
|
|
||||||
And instantiating the module class like::
|
And instantiating the module class like::
|
||||||
|
@ -372,10 +371,7 @@ syntax highlighting before you include it in your Python file.
|
||||||
Example
|
Example
|
||||||
+++++++
|
+++++++
|
||||||
|
|
||||||
To print a basic documentation string, run ``./hacking/module_formatter.py -G``.
|
See an example documentation string in the checkout under examples/DOCUMENTATION.yml
|
||||||
|
|
||||||
You can copy it into your module and use it as a starting point
|
|
||||||
when writing your own docs.
|
|
||||||
|
|
||||||
Include it in your module file like this::
|
Include it in your module file like this::
|
||||||
|
|
||||||
|
@ -389,8 +385,9 @@ Include it in your module file like this::
|
||||||
# ... snip ...
|
# ... snip ...
|
||||||
'''
|
'''
|
||||||
|
|
||||||
The ``description``, and ``notes``
|
The ``description``, and ``notes`` fields
|
||||||
support formatting in some of the output formats (e.g. ``rst``, ``man``).
|
support formatting with some special macros.
|
||||||
|
|
||||||
These formatting functions are ``U()``, ``M()``, ``I()``, and ``C()``
|
These formatting functions are ``U()``, ``M()``, ``I()``, and ``C()``
|
||||||
for URL, module, italic, and constant-width respectively. It is suggested
|
for URL, module, italic, and constant-width respectively. It is suggested
|
||||||
to use ``C()`` for file and option names, and ``I()`` when referencing
|
to use ``C()`` for file and option names, and ``I()`` when referencing
|
||||||
|
@ -405,9 +402,8 @@ like this::
|
||||||
- action: modulename opt1=arg1 opt2=arg2
|
- action: modulename opt1=arg1 opt2=arg2
|
||||||
'''
|
'''
|
||||||
|
|
||||||
The ``module_formatter.py`` script and ``ansible-doc(1)`` append the
|
The EXAMPLES section, just like the documentation section, is required in
|
||||||
``EXAMPLES`` blob after any existing (deprecated) ``examples`` you may have in the
|
all module pull requests for new modules.
|
||||||
YAML ``DOCUMENTATION`` string.
|
|
||||||
|
|
||||||
.. _module_dev_testing:
|
.. _module_dev_testing:
|
||||||
|
|
||||||
|
|
|
@ -23,12 +23,13 @@ This documentation covers the current released version of Ansible (1.4.3) and al
|
||||||
.. _an_introduction:
|
.. _an_introduction:
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 1
|
||||||
|
|
||||||
intro
|
intro
|
||||||
playbooks
|
playbooks
|
||||||
playbooks_special_topics
|
playbooks_special_topics
|
||||||
modules
|
modules
|
||||||
|
modules_by_category
|
||||||
guides
|
guides
|
||||||
developing
|
developing
|
||||||
awx
|
awx
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
Ansible Modules
|
About Modules
|
||||||
===============
|
=============
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 4
|
:maxdepth: 4
|
||||||
|
@ -9,11 +9,10 @@ Ansible Modules
|
||||||
Introduction
|
Introduction
|
||||||
````````````
|
````````````
|
||||||
|
|
||||||
|
|
||||||
Ansible ships with a number of modules (called the 'module library')
|
Ansible ships with a number of modules (called the 'module library')
|
||||||
that can be executed directly on remote hosts or through :doc:`Playbooks <playbooks>`.
|
that can be executed directly on remote hosts or through :doc:`Playbooks <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.
|
handle executing system commands.
|
||||||
|
|
||||||
Let's review how we execute three different modules from the command line::
|
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"
|
ansible webservers -m command -a "/sbin/reboot -t now"
|
||||||
|
|
||||||
Each module supports taking arguments. Nearly all modules take ``key=value``
|
Each module supports taking arguments. Nearly all modules take ``key=value``
|
||||||
arguments, space delimited. Some modules take no arguments, and the
|
arguments, space delimited. Some modules take no arguments, and the command/shell modules simply
|
||||||
command/shell modules simply take the string of the command you want to run.
|
take the string of the command you want to run.
|
||||||
|
|
||||||
From playbooks, Ansible modules are executed in a very similar way::
|
From playbooks, Ansible modules are executed in a very similar way::
|
||||||
|
|
||||||
- name: reboot the servers
|
- name: reboot the servers
|
||||||
action: command /sbin/reboot -t now
|
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
|
- name: reboot the servers
|
||||||
command: /sbin/reboot -t now
|
command: /sbin/reboot -t now
|
||||||
|
|
||||||
All modules technically return JSON format data, though if you are using the
|
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
|
||||||
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.
|
||||||
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
|
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'
|
playbooks, these modules can trigger 'change events' in the form of notifying 'handlers' to run additional tasks.
|
||||||
to run additional tasks.
|
|
||||||
|
|
||||||
Documentation for each module can be accessed from the command line with the
|
Documentation for each module can be accessed from the command line with the ansible-doc tool::
|
||||||
ansible-doc as well as the man command::
|
|
||||||
|
|
||||||
ansible-doc command
|
ansible-doc yum
|
||||||
|
|
||||||
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`.
|
|
||||||
|
|
||||||
.. seealso::
|
.. seealso::
|
||||||
|
|
||||||
|
|
|
@ -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 '''
|
''' dumps module output to a file or the screen, as requested '''
|
||||||
|
|
||||||
if options.output_dir is not None:
|
if options.output_dir is not None:
|
||||||
|
@ -188,7 +188,7 @@ def jinja2_environment(template_dir, typ):
|
||||||
env.filters['fmt'] = rst_fmt
|
env.filters['fmt'] = rst_fmt
|
||||||
env.filters['xline'] = rst_xline
|
env.filters['xline'] = rst_xline
|
||||||
template = env.get_template('rst.j2')
|
template = env.get_template('rst.j2')
|
||||||
outputname = "%s.rst"
|
outputname = "%s_module.rst"
|
||||||
else:
|
else:
|
||||||
raise Exception("unknown module format type: %s" % typ)
|
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.stderr.write("*** ERROR: CORE MODULE MISSING DOCUMENTATION: %s, %s ***\n" % (fname, module))
|
||||||
sys.exit(1)
|
sys.exit(1)
|
||||||
if doc is None:
|
if doc is None:
|
||||||
return
|
return "SKIPPED"
|
||||||
|
|
||||||
all_keys = []
|
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...
|
# here is where we build the table of contents...
|
||||||
|
|
||||||
text = template.render(doc)
|
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]
|
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
|
# TODO: start a new category file
|
||||||
|
|
||||||
category = category.replace("_"," ")
|
category = category.replace("_"," ")
|
||||||
|
@ -266,8 +270,22 @@ def process_category(category, categories, options, env, template, outputname):
|
||||||
modules = module_map.keys()
|
modules = module_map.keys()
|
||||||
modules.sort()
|
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:
|
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
|
# TODO: end a new category file
|
||||||
|
|
||||||
|
@ -305,9 +323,19 @@ def main():
|
||||||
last_category = None
|
last_category = None
|
||||||
category_names = categories.keys()
|
category_names = categories.keys()
|
||||||
category_names.sort()
|
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:
|
for category in category_names:
|
||||||
|
category_list_file.write(" list_of_%s_modules\n" % category)
|
||||||
process_category(category, categories, options, env, template, outputname)
|
process_category(category, categories, options, env, template, outputname)
|
||||||
|
|
||||||
|
category_list_file.close()
|
||||||
|
|
||||||
if __name__ == '__main__':
|
if __name__ == '__main__':
|
||||||
main()
|
main()
|
||||||
|
|
Loading…
Reference in a new issue