Merge pull request #10457 from bcoca/docsite_returnval_docs

Docsite returnval docs

docsite/rst/common_return_values.rst

+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

hacking/module_formatter.py

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

hacking/templates/rst.j2

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