cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge pull request #10457 from bcoca/docsite_returnval_docs

Browse source 
Docsite returnval docs
This commit is contained in:
Brian Coca 2015-03-20 17:27:22 -04:00
commit 3109e7ec68
3 changed files with 112 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -0,0 +1,48 @@
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. Here we document the values common to all modules, each module can optionally document
its own unique returns. If these docs exist they will be visible through ansible-doc and https://docs.ansible.com.
.. _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

4
hacking/module_formatter.py
View file

@ -289,6 +289,10 @@ 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
if returndocs:
doc['returndocs'] = yaml.safe_load(returndocs)
else:
doc['returndocs'] = None
# here is where we build the table of contents...

62
hacking/templates/rst.j2
View file

@ -106,6 +106,64 @@ 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
<table border=1 cellpadding=4>
<tr>
<th class="head">name</th>
<th class="head">despcription</th>
<th class="head">returned</th>
<th class="head">type</th>
<th class="head">sample</th>
</tr>
{% for entry in returndocs %}
<tr>
<td> @{ entry }@ </td>
<td> @{ returndocs[entry].description }@ </td>
<td align=center> @{ returndocs[entry].returned }@ </td>
<td align=center> @{ returndocs[entry].type }@ </td>
<td align=center> @{ returndocs[entry].sample}@ </td>
</tr>
{% if returndocs[entry].type == 'dictionary' %}
<tr><td>contains: </td>
<td colspan=4>
<table border=1 cellpadding=2>
<tr>
<th class="head">name</th>
<th class="head">despcription</th>
<th class="head">returned</th>
<th class="head">type</th>
<th class="head">sample</th>
</tr>
{% for sub in returndocs[entry].contains %}
<tr>
<td> @{ sub }@ </td>
<td> @{ returndocs[entry].contains[sub].description }@ </td>
<td align=center> @{ returndocs[entry].contains[sub].returned }@ </td>
<td align=center> @{ returndocs[entry].contains[sub].type }@ </td>
<td align=center> @{ returndocs[entry].contains[sub].sample}@ </td>
</tr>
{% endfor %}
</table>
</td></tr>
{% endif %}
{% endfor %}
</table>
</br></br>
{% endif %}
{% if notes %}
{% for note in notes %}
.. note:: @{ note | convert_symbols_to_format }@
@ -120,7 +178,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 +193,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>`_.