stable-2.5 docs in sync with devel (#37214)

4 files changed, 208 insertions, 108 deletions

diff --git a/docs/docsite/_themes/sphinx_rtd_theme/footer.html b/docs/docsite/_themes/sphinx_rtd_theme/footer.html
index c7e1e0cb63..2aa10fe780 100644
--- a/docs/docsite/_themes/sphinx_rtd_theme/footer.html
+++ b/docs/docsite/_themes/sphinx_rtd_theme/footer.html
@@ -22,14 +22,7 @@
 </script>
 
   <p>
-  Copyright © 2018 Red Hat, Inc.
-  <br>
-
-  {%- if last_updated %}
-    {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
-  {%- endif %}
+  {%- if last_updated %}{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br/>{% endif %}
+  Copyright © 2018 Red Hat, Inc. <br/>
   </p>
-<p>
-Ansible docs are generated from <a href="https://github.com/ansible/ansible">GitHub sources</a> using <a href="http://sphinx-doc.org/">Sphinx</a> using a theme provided by <a href="http://readthedocs.org">Read the Docs</a>.
-</p>
 </footer>
diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
index c15324ce75..9bb55ccef8 100644
--- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
+++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
@@ -42,7 +42,7 @@ Ansible Release   Latest Version               Status
 ===============   ==========================   =================================================
 devel             `2.5`_ (unreleased, trunk)   In development
 2.4               `2.4.3`_ (2018-01-31)        Supported (security **and** general bug fixes)
-2.3               `2.3.2`_ (2017-08-08)        Supported (security **and** critical bug fixes)
+2.3               `2.3.3`_ (2017-12-20)        Supported (security **and** critical bug fixes)
 2.2               `2.2.3`_ (2017-05-09)        Unsupported (end of life)
 2.1               `2.1.6`_ (2017-06-01)        Unsupported (end of life)
 2.0               `2.0.2`_ (2016-04-19)        Unsupported (end of life)
@@ -56,7 +56,7 @@ devel             `2.5`_ (unreleased, trunk)   In development
 
 .. _2.5: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md
 .. _2.4.3: https://github.com/ansible/ansible/blob/stable-2.4/CHANGELOG.md
-.. _2.3.2: https://github.com/ansible/ansible/blob/stable-2.3/CHANGELOG.md
+.. _2.3.3: https://github.com/ansible/ansible/blob/stable-2.3/CHANGELOG.md
 .. _2.2.3: https://github.com/ansible/ansible/blob/stable-2.2/CHANGELOG.md
 .. _2.1.6: https://github.com/ansible/ansible/blob/stable-2.1/CHANGELOG.md
 .. _2.0.2: https://github.com/ansible/ansible/blob/stable-2.0/CHANGELOG.md
diff --git a/docs/docsite/rst/scenario_guides/guide_aci.rst b/docs/docsite/rst/scenario_guides/guide_aci.rst
index 616c85c8cb..7bc7ee7064 100644
--- a/docs/docsite/rst/scenario_guides/guide_aci.rst
+++ b/docs/docsite/rst/scenario_guides/guide_aci.rst
@@ -51,7 +51,7 @@ Using the ACI modules
 ---------------------
 The Ansible ACI modules provide a user-friendly interface to managing your ACI environment using Ansible playbooks.
 
-For instance ensuring that a specific tenant exists, is done using the following Ansible task:
+For instance ensuring that a specific tenant exists, is done using the following Ansible task using module `aci_tenant <aci_tenant>`:
 
 .. code-block:: yaml
 
@@ -67,6 +67,37 @@ For instance ensuring that a specific tenant exists, is done using the following
 
 A complete list of existing ACI modules is available for `the latest stable release <http://docs.ansible.com/ansible/latest/modules/list_of_network_modules.html#aci>`_ as well as `the current development version <http://docs.ansible.com/ansible/devel/modules/list_of_network_modules.html#aci>`_.
 
+Querying ACI configuration
+..........................
+
+A module can also be used to query a specific object.
+
+.. code-block:: yaml
+
+    - name: Query tenant customer-xyz
+      aci_tenant:
+        host: my-apic-1
+        username: admin
+        password: my-password
+    
+      tenant: customer-xyz
+      state: query
+
+Or query all objects.
+
+.. code-block:: yaml
+
+    - name: Query all tenants
+      aci_tenant:
+        host: my-apic-1
+        username: admin
+        password: my-password
+    
+        state: query
+      register: all_tenants
+
+After registering the return values of the `aci_tenant <aci_tenant>` task as shown above, you can access all tenant information from variable ``all_tenants``.
+
 
 Common parameters
 .................
@@ -125,7 +156,7 @@ Return values
 The following values are always returned:
 
     current
-        The resulting state of the managed object.
+        The resulting state of the managed object, or results of your query.
 
 The following values are returned when ``output_level: info``:
 
@@ -173,7 +204,7 @@ ACI authentication
 
 Password-based authentication
 .............................
-If you want to logon using a username and password, you can use the following parameters with your ACI modules:
+If you want to log on using a username and password, you can use the following parameters with your ACI modules:
 
 .. code-block:: yaml
 
@@ -208,16 +239,16 @@ Configure your local user
 ,,,,,,,,,,,,,,,,,,,,,,,,,
 Perform the following steps:
 
-- Add the X.509 certificate to your ACI AAA local user at **ADMIN > AAA**
-- Click **AAA Authentication**
-- Check that in the **Authentication** field the **Realm** field displays **Local**
-- Expand **Security Management > Local Users**
-- Click the name of the user you want to add a certificate to, in the **User Certificates** area
-- Click the **+** sign and in the **Create X509 Certificate** enter a certificate name in the **Name** field
+- Add the X.509 certificate to your ACI AAA local user at :guilabel:`ADMIN` » :guilabel:`AAA`
+- Click :guilabel:`AAA Authentication`
+- Check that in the :guilabel:`Authentication` field the :guilabel:`Realm` field displays :guilabel:`Local`
+- Expand :guilabel:`Security Management` » :guilabel:`Local Users`
+- Click the name of the user you want to add a certificate to, in the :guilabel:`User Certificates` area
+- Click the :guilabel:`+` sign and in the :guilabel:`Create X509 Certificate` enter a certificate name in the :guilabel:`Name` field
 
   * If you use the basename of your private key here, you don't need to enter ``certificate_name`` in Ansible
 
-- Copy and paste your X.509 certificate in the **Data** field.
+- Copy and paste your X.509 certificate in the :guilabel:`Data` field.
 
 You can automate this by using the following Ansible task:
 
diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2
index e3c07604d6..66a7b717fd 100644
--- a/docs/templates/plugin.rst.j2
+++ b/docs/templates/plugin.rst.j2
@@ -13,11 +13,8 @@
 
 {% if version_added is defined and version_added != '' -%}
 .. versionadded:: @{ version_added | default('') }@
-
-
 {% endif %}
 
-
 .. contents::
    :local:
    :depth: 2
@@ -33,7 +30,6 @@
 
 DEPRECATED
 ----------
-
 {# use unknown here? skip the fields? #}
 :Removed in Ansible: version: @{ deprecated['removed_in'] | default('') | string | convert_symbols_to_format }@
 :Why: @{ deprecated['why'] | default('') | convert_symbols_to_format }@
@@ -44,45 +40,42 @@ DEPRECATED
 
 Synopsis
 --------
-
-{% if description %}
+{% if description -%}
 
 {%   if description is string -%}
-* @{ description | convert_symbols_to_format }@
+- @{ description | convert_symbols_to_format }@
 {%   else %}
-{%     for desc in description -%}
-* @{ desc | convert_symbols_to_format }@
+{%     for desc in description %}
+- @{ desc | convert_symbols_to_format }@
 {%     endfor %}
 {%   endif %}
 
 {% endif %}
 
 {% if aliases is defined -%}
-
 Aliases: @{ ','.join(aliases) }@
-
-
 {% endif %}
 
-{% if requirements %}
-{%   set req_title = 'Requirements' %}
+{% if requirements -%}
+
+Requirements
+~~~~~~~~~~~~
 {%   if plugin_type == 'module' %}
-{%     set req_title = req_title + ' (on host that executes module)' %}
+The below requirements are needed on the host that executes this @{ plugin_type }@.
+{%   else %}
+The below requirements are needed on the local master node that executes this @{ plugin_type }@.
 {%   endif %}
-@{ req_title }@
-@{ '-' * req_title|length }@
 
 {%   for req in requirements %}
-* @{ req | convert_symbols_to_format }@
+- @{ req | convert_symbols_to_format }@
 {%   endfor %}
 
 {% endif %}
 
 {% if options -%}
 
-
-Options
--------
+Parameters
+----------
 
 .. raw:: html
 
@@ -90,47 +83,55 @@ Options
         {# Header of the documentation #}
         <tr>
             <th class="head"><div class="cell-border">Parameter</div></th>
-            <th class="head"><div class="cell-border">Default</div></th>
-            <th class="head"><div class="cell-border">Choices</div></th>
+            <th class="head"><div class="cell-border">Choices/<font color="blue">Defaults</font></div></th>
             {% if plugin_type != 'module' %}
                 <th class="head"><div class="cell-border">Configuration</div></th>
             {% endif %}
-            <th class="head"><div class="cell-border">Comments</div></th>
+            <th class="head" width="100%"><div class="cell-border">Comments</div></th>
         </tr>
         {% for key, value in options|dictsort recursive %}
             <tr class="return-value-column">
-                {# parameter name with introduced label #}
+                {# parameter name with required and/or introduced label #}
                 <td>
                     <div class="outer-elbow-container">
                         {% for i in range(1, loop.depth) %}
-                            <div class="elbow-placeholder">
-                            </div>
+                            <div class="elbow-placeholder"></div>
                         {% endfor %}
                         <div class="elbow-key">
                             <b>@{ key }@</b>
                             {% if value.get('required', False) %}<br/><div style="font-size: small; color: red">required</div>{% endif %}
                             {% if value.version_added %}<br/><div style="font-size: small; color: darkgreen">(added in @{value.version_added}@)</div>{% endif %}
                         </div>
-                    <div class="outer-elbow-container">
+                    </div>
                 </td>
-                {# default value #}
-                <td><div class="cell-border">{% if value.default %}@{ value.default | html_ify }@{% endif %}</div></td>
-                {# choices #}
+                {# default / choices #}
                 <td>
                     <div class="cell-border">
+                        {% if value.default is defined %}
+                            {% if value.default == true %}
+                                {% set _x = value.update({'default': 'yes'}) %}
+                            {% elif value.default == false %}
+                                {% set _x = value.update({'default': 'no'}) %}
+                            {% endif %}
+                        {% endif %}
                         {% if value.type == 'bool' %}
-                            <ul>
-                                <li>yes</li>
-                                <li>no</li>
-                            </ul>
-                        {% else %}
-                            {% if value.choices %}
-                                <ul>
-                                    {% for choice in value.choices %}
+                            {% set _x = value.update({'choices': ['no', 'yes']}) %}
+                        {% endif %}
+                        {% if value.choices %}
+                            <ul style="list-style-type: circle"><b>Choices:</b>
+                                {% if value.default not in value.choices %}
+                                    <li type="disc"><div style="color: blue"><b>@{ value.default }@</b>&nbsp;&larr;</div></li>
+                                {% endif %}
+                                {% for choice in value.choices %}
+                                    {% if value.default is defined and choice == value.default %}
+                                        <li type="disc"><div style="color: blue"><b>@{ value.default }@</b>&nbsp;&larr;</div></li>
+                                    {% else %}
                                         <li>@{ choice }@</li>
-                                    {% endfor %}
-                                </ul>
-                            {% endif %}
+                                    {% endif %}
+                                {% endfor %}
+                            </ul>
+                        {% elif value.default is defined %}
+                            <div style="color: blue">@{ value.default | html_ify }@</div>
                         {% endif %}
                     </div>
                 </td>
@@ -169,7 +170,7 @@ Options
                             {% endfor %}
                         {% endif %}
                         {% if 'aliases' in value and value.aliases %}
-                            </br><div style="font-size: small;">aliases: @{ value.aliases|join(', ') }@</div>
+                            <div style="font-size: small; color: darkgreen"><br/>aliases: @{ value.aliases|join(', ') }@</div>
                         {% endif %}
                     </div>
                 </td>
@@ -183,11 +184,11 @@ Options
             {% endif %}
         {% endfor %}
     </table>
-    </br>
+    <br/>
 
 {% endif %}
-{% if notes -%}
 
+{% if notes -%}
 
 Notes
 -----
@@ -197,10 +198,9 @@ Notes
     - @{ note | convert_symbols_to_format }@
 {%   endfor %}
 
-
 {% endif %}
-{% if examples or plainexamples -%}
 
+{% if examples or plainexamples -%}
 
 Examples
 --------
@@ -212,28 +212,29 @@ Examples
 @{ example['code'] | escape | indent(4, True) }@
 {%   endfor %}
 {%   if plainexamples %}@{ plainexamples | indent(4, True) }@{% endif %}
-{% endif %}
 
+{% endif %}
 
-{% if returndocs -%}
-
+{% if not returnfacts and returndocs and returndocs.ansible_facts is defined %}
+{%   set returnfacts = returndocs.ansible_facts.contains %}
+{%   set _x = returndocs.pop('ansible_facts', None) %}
+{% endif %}
 
-Return Values
--------------
+{% if returnfacts -%}
 
-Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this @{ plugin_type }@:
+Returned Facts
+--------------
+Facts returned by this module are added/updated in the ``hostvars`` host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them.
 
 .. raw:: html
 
     <table border=0 cellpadding=0 class="documentation-table">
         <tr>
-            <th class="head"><div class="cell-border">Name</div></th>
-            <th class="head"><div class="cell-border">Description</div></th>
+            <th class="head"><div class="cell-border">Fact</div></th>
             <th class="head"><div class="cell-border">Returned</div></th>
-            <th class="head"><div class="cell-border">Type</div></th>
-            <th class="head"><div class="cell-border">Sample</div></th>
+            <th class="head" width="100%"><div class="cell-border">Description</div></th>
         </tr>
-        {% for key, value in returndocs|dictsort recursive %}
+        {% for key, value in returnfacts|dictsort recursive %}
             <tr class="return-value-column">
                 <td>
                     <div class="outer-elbow-container">
@@ -243,21 +244,28 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
                         {% endfor %}
                         <div class="elbow-key">
                             <b>@{ key }@</b>
+                            <br/><div style="font-size: small; color: red">@{ value.type }@</div>
                         </div>
                     </div>
                 </td>
+                <td><div class="cell-border">@{ value.returned }@</div></td>
                 <td>
-                    {% if value.description is string %}
-                        <div class="cell-border">@{ value.description | replace('\n', '\n    ') | html_ify }@</div>
-                    {% else %}
-                    {% for desc in value.description %}
-                        <div class="cell-border">@{ desc | replace('\n', '\n    ') | html_ify }@</div>
-                    {% endfor %}
-                    {% endif %}
+                    <div class="cell-border">
+                        {% if value.description is string %}
+                            <div>@{ value.description | html_ify }@</div>
+                        {% else %}
+                            {% for desc in value.description %}
+                                <div>@{ desc | html_ify }@</div>
+                            {% endfor %}
+                        {% endif %}
+                        <br/>
+                        {% if value.sample %}
+                            <div style="font-size: smaller"><b>Sample:</b></div>
+{#                            <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #}
+                            <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div>
+                        {% endif %}
+                    </div>
                 </td>
-                <td><div class="cell-border">@{ value.returned }@</div></td>
-                <td><div class="cell-border">@{ value.type }@</div></td>
-                <td><div class="cell-border">@{ value.sample | replace('\n', '\n    ') | html_ify }@</div></td>
             </tr>
             {# ---------------------------------------------------------
              # sadly we cannot blindly iterate through the child dicts,
@@ -273,49 +281,117 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
             {% endif %}
         {% endfor %}
     </table>
-    </br></br>
-{% endif %}
+    <br/><br/>
 
+{% endif %}
 
-{% if author is defined -%}
-
+{% if returndocs -%}
 
-Author
-~~~~~~
+Return Values
+-------------
+Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this @{ plugin_type }@:
 
-{%   for author_name in author %}
-* @{ author_name }@
-{%   endfor %}
+.. raw:: html
 
+    <table border=0 cellpadding=0 class="documentation-table">
+        <tr>
+            <th class="head"><div class="cell-border">Key</div></th>
+            <th class="head"><div class="cell-border">Returned</div></th>
+            <th class="head" width="100%"><div class="cell-border">Description</div></th>
+        </tr>
+        {% for key, value in returndocs|dictsort recursive %}
+            <tr class="return-value-column">
+                <td>
+                    <div class="outer-elbow-container">
+                        {% for i in range(1, loop.depth) %}
+                            <div class="elbow-placeholder">
+                            </div>
+                        {% endfor %}
+                        <div class="elbow-key">
+                            <b>@{ key }@</b>
+                            <br/><div style="font-size: small; color: red">@{ value.type }@</div>
+                        </div>
+                    </div>
+                </td>
+                <td><div class="cell-border">@{ value.returned }@</div></td>
+                <td>
+                    <div class="cell-border">
+                        {% if value.description is string %}
+                            <div>@{ value.description | html_ify }@</div>
+                        {% else %}
+                            {% for desc in value.description %}
+                                <div>@{ desc | html_ify }@</div>
+                            {% endfor %}
+                        {% endif %}
+                        <br/>
+                        {% if value.sample %}
+                            <div style="font-size: smaller"><b>Sample:</b></div>
+{#                            <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #}
+                            <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div>
+                        {% endif %}
+                    </div>
+                </td>
+            </tr>
+            {# ---------------------------------------------------------
+             # sadly we cannot blindly iterate through the child dicts,
+             # since in some documentations,
+             # lists are used instead of dicts. This handles both types
+             # ---------------------------------------------------------#}
+            {% if value.contains %}
+                {% if value.contains.items %}
+                    @{ loop(value.contains.items()) }@
+                {% elif value.contains[0].items %}
+                    @{ loop(value.contains[0].items()) }@
+                {% endif %}
+            {% endif %}
+        {% endfor %}
+    </table>
+    <br/><br/>
 
 {% endif %}
+
+Status
+------
 {% if not deprecated %}
+
 {%   set support = { 'core': 'The Ansible Core Team', 'network': 'The Ansible Network Team', 'certified': 'an Ansible Partner', 'community': 'The Ansible Community', 'curated': 'A Third Party'} %}
 {%   set module_states = { 'preview': 'it is not guaranteed to have a backwards compatible interface', 'stableinterface': 'the maintainers for this module guarantee that no backward incompatible interface changes will be made'} %}
+
 {%   if metadata %}
 {%     if metadata.status %}
 
-
-Status
-~~~~~~
-
 {%       for cur_state in metadata.status %}
 This module is flagged as **@{cur_state}@** which means that @{module_states[cur_state]}@.
 {%       endfor %}
 
-
 {%     endif %}
-{%     if metadata.supported_by in ('core', 'network') %}
 
+{%     if metadata.supported_by in ('core', 'network') %}
 
-Maintenance Info
-~~~~~~~~~~~~~~~~
-
+Support
+~~~~~~~
 For more information about Red Hat's support of this @{ plugin_type }@,
 please refer to this `Knowledge Base article <https://access.redhat.com/articles/rhel-top-support-policies/>`_
 
 {%     endif %}
 {%   endif %}
+
+{% else %}
+
+This module is flagged as **deprecated** and will be removed in version { deprecated['removed_in'] | default('') | string | convert_symbols_to_format }@. For more information see :ref:`DEPRECATED`.
+
+{% endif %}
+
+{% if author is defined -%}
+
+Author
+~~~~~~
+
+{%   for author_name in author %}
+- @{ author_name }@
+{%   endfor %}
+
 {% endif %}
 
-If you notice any issues in this documentation you can `edit this document <https://github.com/ansible/ansible/edit/devel/lib/ansible/modules/@{ source }@?description=%3C!---%20Your%20description%20here%20--%3E%0A%0A+label:%20docsite_pr>`_ to improve it.
+.. hint::
+    If you notice any issues in this documentation you can `edit this document <https://github.com/ansible/ansible/edit/devel/lib/ansible/modules/@{ source }@?description=%3C!---%20Your%20description%20here%20--%3E%0A%0A+label:%20docsite_pr>`_ to improve it.