diff --git a/docsite/rst/common_return_values.rst b/docsite/rst/common_return_values.rst new file mode 100644 index 0000000000..ff2b92b4af --- /dev/null +++ b/docsite/rst/common_return_values.rst @@ -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 `_ + Browse source of core modules + `Mailing List `_ + Development mailing list + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index 1bc83ad930..c3aca94949 100755 --- a/hacking/module_formatter.py +++ b/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... diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index e5562d3e56..6873c3fea5 100644 --- a/hacking/templates/rst.j2 +++ b/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 + + + + + + + + + + + {% for entry in returndocs %} + + + + + + + + {% if returndocs[entry].type == 'dictionary' %} + + + + {% endif %} + {% endfor %} + +
namedespcriptionreturnedtypesample
@{ entry }@ @{ returndocs[entry].description }@ @{ returndocs[entry].returned }@ @{ returndocs[entry].type }@ @{ returndocs[entry].sample}@
contains: + + + + + + + + + + {% for sub in returndocs[entry].contains %} + + + + + + + + {% endfor %} + +
namedespcriptionreturnedtypesample
@{ sub }@ @{ returndocs[entry].contains[sub].description }@ @{ returndocs[entry].contains[sub].returned }@ @{ returndocs[entry].contains[sub].type }@ @{ returndocs[entry].contains[sub].sample}@
+
+

+{% 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 `_ 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 `_ 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 `_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group `_. @@ -135,7 +193,7 @@ This is an Extras Module ------------------------ This source of this module is hosted on GitHub in the `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 `_ 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 ` or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group `_.