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

Added return values documentation to modules

Browse source
This commit is contained in:
Brian Coca 2015-03-13 11:43:02 -04:00
parent 393246fdd3
commit 94909bd4a2
3 changed files with 65 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
docsite/rst/common_return_values.rst Normal file
View file

@ -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

1
hacking/module_formatter.py
View file

@ -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...

19
hacking/templates/rst.j2
View file

@ -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 }@
@ -120,7 +135,7 @@ This is a Core Module
---------------------
This source of this module is hosted on GitHub in the `ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ repo.
If you believe you have found a bug in this module, and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ to see if a bug has already been filed. If not, we would be grateful if you would file one.
Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
@ -135,7 +150,7 @@ This is an Extras Module
------------------------
This source of this module is hosted on GitHub in the `ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ repo.
If you believe you have found a bug in this module, and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ to see if a bug has already been filed. If not, we would be grateful if you would file one.
Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>` or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.