From 94909bd4a2ce31d13378980b126953dcf38f555a Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 13 Mar 2015 11:43:02 -0400 Subject: [PATCH 1/5] Added return values documentation to modules --- docsite/rst/common_return_values.rst | 47 ++++++++++++++++++++++++++++ hacking/module_formatter.py | 1 + hacking/templates/rst.j2 | 19 +++++++++-- 3 files changed, 65 insertions(+), 2 deletions(-) create mode 100644 docsite/rst/common_return_values.rst diff --git a/docsite/rst/common_return_values.rst b/docsite/rst/common_return_values.rst new file mode 100644 index 0000000000..ebee58c1c2 --- /dev/null +++ b/docsite/rst/common_return_values.rst @@ -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 `_ + 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..6d595c634d 100755 --- a/hacking/module_formatter.py +++ b/hacking/module_formatter.py @@ -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... diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index e5562d3e56..122cebb590 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -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 +
+@{ returndocs }@
+
+ +:: +{% 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 `_ 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 +150,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 `_. From 690d227034354a8f6cc286de029344a70cfb9830 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 13 Mar 2015 11:45:22 -0400 Subject: [PATCH 2/5] extended return value explanation --- docsite/rst/common_return_values.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docsite/rst/common_return_values.rst b/docsite/rst/common_return_values.rst index ebee58c1c2..38a6917233 100644 --- a/docsite/rst/common_return_values.rst +++ b/docsite/rst/common_return_values.rst @@ -3,8 +3,9 @@ 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. +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 +it's own unique returns. If these docs exist they will be visible through ansible-doc and https://docs.ansible.com. .. _facts: From 2cacac4b23c6979daf8e037738d152afac78899d Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 13 Mar 2015 12:17:15 -0400 Subject: [PATCH 3/5] minor adjustments to formatting --- hacking/templates/rst.j2 | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index 122cebb590..6d3c21f424 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -114,11 +114,15 @@ Return Values Common return values are documented here ::doc::`common_return_values`, the following are the fields unique to this module: .. raw:: html -
-@{ returndocs }@
-
+ +

+ 

+    @{ returndocs }@
+
+

:: + {% endif %} {% if notes %} From 64b447f01bf5338195627eff2fec4e62257f6f02 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 13 Mar 2015 12:22:55 -0400 Subject: [PATCH 4/5] grammer correction --- docsite/rst/common_return_values.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docsite/rst/common_return_values.rst b/docsite/rst/common_return_values.rst index 38a6917233..ff2b92b4af 100644 --- a/docsite/rst/common_return_values.rst +++ b/docsite/rst/common_return_values.rst @@ -5,7 +5,7 @@ Common Return Values 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 -it's own unique returns. If these docs exist they will be visible through ansible-doc and https://docs.ansible.com. +its own unique returns. If these docs exist they will be visible through ansible-doc and https://docs.ansible.com. .. _facts: From c3076b84788f78a075764e4d9e8fb28fef5db60c Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 20 Mar 2015 16:54:22 -0400 Subject: [PATCH 5/5] added module returnval documentation to web docs --- hacking/module_formatter.py | 5 +++- hacking/templates/rst.j2 | 53 ++++++++++++++++++++++++++++++++----- 2 files changed, 50 insertions(+), 8 deletions(-) diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index 6d595c634d..c3aca94949 100755 --- a/hacking/module_formatter.py +++ b/hacking/module_formatter.py @@ -289,7 +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 - doc['returndocs'] = returndocs + 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 6d3c21f424..6873c3fea5 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -111,18 +111,57 @@ Examples Return Values ------------- -Common return values are documented here ::doc::`common_return_values`, the following are the fields unique to this module: +Common return values are documented here :doc:`common_return_values`, the following are the fields unique to this module: .. raw:: html -

- 

-    @{ returndocs }@
-
-

+ + + + + + + + -:: + {% 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 %}