From 4df0be4b1bbe91c0a5b0b9d41b9edb1092f86430 Mon Sep 17 00:00:00 2001 From: John R Barker Date: Thu, 8 Mar 2018 20:04:16 +0000 Subject: [PATCH] stable-2.5 docs in sync with devel (#37214) --- .../_themes/sphinx_rtd_theme/footer.html | 11 +- .../release_and_maintenance.rst | 4 +- .../docsite/rst/scenario_guides/guide_aci.rst | 51 +++- docs/templates/plugin.rst.j2 | 250 ++++++++++++------ 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 c7e1e0cb636..2aa10fe7808 100644 --- a/docs/docsite/_themes/sphinx_rtd_theme/footer.html +++ b/docs/docsite/_themes/sphinx_rtd_theme/footer.html @@ -22,14 +22,7 @@

- Copyright © 2018 Red Hat, Inc. -
- - {%- 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 %}
{% endif %} + Copyright © 2018 Red Hat, Inc.

-

-Ansible docs are generated from GitHub sources using Sphinx using a theme provided by Read the Docs. -

diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index c15324ce75a..9bb55ccef8c 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 616c85c8cb7..7bc7ee7064a 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 `: .. 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 `_ as well as `the current development version `_. +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 ` 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 e3c07604d6c..66a7b717fdd 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 #}
Parameter
-
Default
-
Choices
+
Choices/Defaults
{% if plugin_type != 'module' %}
Configuration
{% endif %} -
Comments
+
Comments
{% for key, value in options|dictsort recursive %} - {# parameter name with introduced label #} + {# parameter name with required and/or introduced label #}
{% for i in range(1, loop.depth) %} -
-
+
{% endfor %}
@{ key }@ {% if value.get('required', False) %}
required
{% endif %} {% if value.version_added %}
(added in @{value.version_added}@)
{% endif %}
-
+
- {# default value #} -
{% if value.default %}@{ value.default | html_ify }@{% endif %}
- {# choices #} + {# default / choices #}
+ {% 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' %} -
    -
  • yes
    • -
  • no
    • -
- {% else %} - {% if value.choices %} -
    - {% for choice in value.choices %} + {% set _x = value.update({'choices': ['no', 'yes']}) %} + {% endif %} + {% if value.choices %} +
      Choices: + {% if value.default not in value.choices %} +
    • @{ value.default }@ ←
      • + {% endif %} + {% for choice in value.choices %} + {% if value.default is defined and choice == value.default %} +
    • @{ value.default }@ ←
      • + {% else %}
    • @{ choice }@
      • - {% endfor %} -
    - {% endif %} + {% endif %} + {% endfor %} +
+ {% elif value.default is defined %} +
@{ value.default | html_ify }@
{% endif %}
@@ -169,7 +170,7 @@ Options {% endfor %} {% endif %} {% if 'aliases' in value and value.aliases %} -
aliases: @{ value.aliases|join(', ') }@
+

aliases: @{ value.aliases|join(', ') }@
{% endif %}
@@ -183,11 +184,11 @@ Options {% endif %} {% endfor %} -
+
{% 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 `, 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 - - + - - + - {% for key, value in returndocs|dictsort recursive %} + {% for key, value in returnfacts|dictsort recursive %} + - - - {# --------------------------------------------------------- # sadly we cannot blindly iterate through the child dicts, @@ -273,49 +281,117 @@ Common return values are documented :ref:`here `, the foll {% endif %} {% endfor %}
Name
Description
Fact
Returned
Type
Sample
Description
@@ -243,21 +244,28 @@ Common return values are documented :ref:`here `, the foll {% endfor %}
@{ key }@ +
@{ value.type }@
@{ value.returned }@
 - {% if value.description is string %} -
@{ value.description | replace('\n', '\n ') | html_ify }@
- {% else %} - {% for desc in value.description %} -
@{ desc | replace('\n', '\n ') | html_ify }@
- {% endfor %} - {% endif %} +
+ {% if value.description is string %} +
@{ value.description | html_ify }@
+ {% else %} + {% for desc in value.description %} +
@{ desc | html_ify }@
+ {% endfor %} + {% endif %} +
+ {% if value.sample %} +
Sample:
+{#
@{ value.sample | html_ify }@
#} +
@{ value.sample | html_ify }@
+ {% endif %} +
@{ value.returned }@
@{ value.type }@
@{ value.sample | replace('\n', '\n ') | html_ify }@
-

-{% endif %} +

+{% endif %} -{% if author is defined -%} - +{% if returndocs -%} -Author -~~~~~~ +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this @{ plugin_type }@: -{% for author_name in author %} -* @{ author_name }@ -{% endfor %} +.. raw:: html + + + + + + + {% for key, value in returndocs|dictsort recursive %} + + + + + + {# --------------------------------------------------------- + # 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 %} +
Key
Returned
Description
+
+ {% for i in range(1, loop.depth) %} +
+
+ {% endfor %} +
+ @{ key }@ +
@{ value.type }@
+
+
+
@{ value.returned }@
 +
+ {% if value.description is string %} +
@{ value.description | html_ify }@
+ {% else %} + {% for desc in value.description %} +
@{ desc | html_ify }@
+ {% endfor %} + {% endif %} +
+ {% if value.sample %} +
Sample:
+{#
@{ value.sample | html_ify }@
#} +
@{ value.sample | html_ify }@
+ {% endif %} +
+
+

{% 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 `_ {% 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 `_ to improve it. +.. hint:: + If you notice any issues in this documentation you can `edit this document `_ to improve it.