Added return values documentation to modules

pull/10457/head
Brian Coca 10 years ago
parent 393246fdd3
commit 94909bd4a2

@ -0,0 +1,47 @@
Common Return Values
====================
.. contents:: Topics
Ansible modules normally return a data structure that can be registered into a variable,
or seen directly when using the `ansible` program as output.
.. _facts:
Facts
`````
Some modules return 'facts' to ansible (i.e setup), this is done through a 'ansible_facts' key and anything inside
will automatically be available for the current host directly as a variable and there is no need to
register this data.
.. _status:
Status
``````
Every module must return a status, saying if the module was successful, if anything changed or not. Ansible itself
will return a status if it skips the module due to a user condition (when: ) or running in check mode when the module
does not support it.
.. _other:
Other common returns
````````````````````
It is common on failure or success to return a 'msg' that either explains the failure or makes a note about the execution.
Some modules, specifically those that execute shell or commands directly, will return stdout and stderr, if ansible sees
a stdout in the results it will append a stdout_lines which is just a list or the lines in stdout.
.. seealso::
:doc:`modules`
Learn about available modules
`GitHub modules directory <https://github.com/ansible/ansible/tree/devel/library>`_
Browse source of core modules
`Mailing List <http://groups.google.com/group/ansible-devel>`_
Development mailing list
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

@ -289,6 +289,7 @@ def process_module(module, options, env, template, outputname, module_map, alias
doc['now_date'] = datetime.date.today().strftime('%Y-%m-%d')
doc['ansible_version'] = options.ansible_version
doc['plainexamples'] = examples #plain text
doc['returndocs'] = returndocs
# here is where we build the table of contents...

@ -106,6 +106,21 @@ Examples
{% endif %}
{% endif %}
{% if returndocs %}
Return Values
-------------
Common return values are documented here ::doc::`common_return_values`, the following are the fields unique to this module:
.. raw:: html
<pre>
@{ returndocs }@
</pre>
::
{% endif %}
{% if notes %}
{% for note in notes %}
.. note:: @{ note | convert_symbols_to_format }@

Loading…
Cancel
Save