@@ -37,6 +37,8 @@ docs/docsite/rst/cli/ansible.rst

 docs/docsite/rst/dev_guide/collections_galaxy_meta.rst

 docs/docsite/rst/dev_guide/testing/sanity/index.rst.new

 docs/docsite/rst/modules/*.rst

+docs/docsite/rst/collections/*.rst

+docs/docsite/rst/collections/*/*.rst

 docs/docsite/rst/playbooks_directives.rst

 docs/docsite/rst/plugins_by_category.rst

 docs/docsite/rst/plugins/*/*.rst

@@ -277,7 +277,7 @@ linkcheckdocs:

 .PHONY: generate_rst

 generate_rst: lib/ansible/cli/*.py

 	mkdir -p ./docs/man/man1/ ; \

-	PYTHONPATH=./lib $(GENERATE_CLI) --template-file=docs/templates/man.j2 --output-dir=docs/man/man1/ --output-format man lib/ansible/cli/*.py

+	$(GENERATE_CLI) --template-file=docs/templates/man.j2 --output-dir=docs/man/man1/ --output-format man lib/ansible/cli/*.py

 docs: generate_rst

@@ -1,6 +1,6 @@

 OS := $(shell uname -s)

 SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"):

-PLUGIN_FORMATTER=../../hacking/build-ansible.py document-plugins

+PLUGIN_FORMATTER=../../hacking/build-ansible.py docs-build

 TESTING_FORMATTER=../bin/testing_formatter.sh

 KEYWORD_DUMPER=../../hacking/build-ansible.py document-keywords

 CONFIG_DUMPER=../../hacking/build-ansible.py document-config

@@ -12,23 +12,35 @@ else

 CPUS ?= $(shell nproc)

 endif

-# Sets the build output directory if it's not already specified

+# Sets the build output directory for the main docsite if it's not already specified

 ifndef BUILDDIR

 	BUILDDIR = _build

 endif

-MODULE_ARGS=

+# Backwards compat for separate VARS

+PLUGIN_ARGS=

 ifdef MODULES

-	MODULE_ARGS = -l $(MODULES)

+ifndef PLUGINS

+	PLUGIN_ARGS = -l $(MODULES)

+else

+	PLUGIN_ARGS = -l $(MODULES),$(PLUGINS)

 endif

-

-PLUGIN_ARGS=

+else

 ifdef PLUGINS

 	PLUGIN_ARGS = -l $(PLUGINS)

 endif

+endif

+

 DOC_PLUGINS ?= become cache callback cliconf connection httpapi inventory lookup netconf shell strategy vars

+PYTHON=python

+# fetch version from project release.py as single source-of-truth

+VERSION := $(shell $(PYTHON) ../../packaging/release/versionhelper/version_helper.py --raw || echo error)

+ifeq ($(findstring error,$(VERSION)), error)

+$(error "version_helper failed")

+endif

+

 assertrst:

 ifndef rst

 	$(error specify document or pattern with rst=somefile.rst)

@@ -38,17 +50,24 @@ all: docs

 docs: htmldocs

-generate_rst: collections_meta config cli keywords modules plugins testing

+generate_rst: collections_meta config cli keywords plugins testing

+base_generate_rst: collections_meta config cli keywords base_plugins testing

 htmldocs: generate_rst

 	CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html

+base_htmldocs: base_generate_rst

+	CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html

+

 singlehtmldocs: generate_rst

 	CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml

+base_singlehtmldocs: base_generate_rst

+	CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml

+

 linkcheckdocs: generate_rst

 		CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx linkcheck

-		

+

 webdocs: docs

 #TODO: leaving htmlout removal for those having older versions, should eventually be removed also

@@ -58,7 +77,7 @@ clean:

 	-rm -rf $(BUILDDIR)/html

 	-rm -rf htmlout

 	-rm -rf module_docs

-	-rm -rf _build

+	-rm -rf $(BUILDDIR)

 	-rm -f .buildinfo

 	-rm -f objects.inv

 	-rm -rf *.doctrees

@@ -70,43 +89,44 @@ clean:

 	find . -type f \( -name "*~" -or -name "#*" \) -delete

 	find . -type f \( -name "*.swp" \) -delete

 	@echo "Cleaning up generated rst"

-	rm -f rst/modules/*_by_category.rst

-	rm -f rst/modules/list_of_*.rst

-	rm -f rst/modules/*_maintained.rst

-	rm -f rst/modules/*_module.rst

-	rm -f rst/modules/*_plugin.rst

 	rm -f rst/playbooks_directives.rst

-	rm -f rst/plugins/*/*.rst

 	rm -f rst/reference_appendices/config.rst

 	rm -f rst/reference_appendices/playbooks_keywords.rst

 	rm -f rst/dev_guide/collections_galaxy_meta.rst

 	rm -f rst/cli/*.rst

+	rm -rf rst/collections/*

+	@echo "Cleaning up legacy generated rst locations"

+	rm -rf rst/modules

+	rm -f rst/plugins/*/*.rst

 .PHONY: docs clean

 collections_meta: ../templates/collections_galaxy_meta.rst.j2

-	PYTHONPATH=../../lib $(COLLECTION_DUMPER) --template-file=../templates/collections_galaxy_meta.rst.j2 --output-dir=rst/dev_guide/ ../../lib/ansible/galaxy/data/collections_galaxy_meta.yml

+	$(COLLECTION_DUMPER) --template-file=../templates/collections_galaxy_meta.rst.j2 --output-dir=rst/dev_guide/ ../../lib/ansible/galaxy/data/collections_galaxy_meta.yml

 # TODO: make generate_man output dir cli option

 cli:

 	mkdir -p rst/cli

-	PYTHONPATH=../../lib $(GENERATE_CLI) --template-file=../templates/cli_rst.j2 --output-dir=rst/cli/ --output-format rst ../../lib/ansible/cli/*.py

+	$(GENERATE_CLI) --template-file=../templates/cli_rst.j2 --output-dir=rst/cli/ --output-format rst ../../lib/ansible/cli/*.py

 keywords: ../templates/playbooks_keywords.rst.j2

-	PYTHONPATH=../../lib $(KEYWORD_DUMPER) --template-dir=../templates --output-dir=rst/reference_appendices/ ./keyword_desc.yml

+	$(KEYWORD_DUMPER) --template-dir=../templates --output-dir=rst/reference_appendices/ ./keyword_desc.yml

 config: ../templates/config.rst.j2

-	PYTHONPATH=../../lib $(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/ ../../lib/ansible/config/base.yml

-

-modules: ../templates/plugin.rst.j2

-	PYTHONPATH=../../lib $(PLUGIN_FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/modules/ $(MODULE_ARGS)

-

-plugins: ../templates/plugin.rst.j2

-	@echo "looping over doc plugins"

-	for plugin in $(DOC_PLUGINS); \

-	do \

-		PYTHONPATH=../../lib $(PLUGIN_FORMATTER) -t rst --plugin-type $$plugin --template-dir=../templates --module-dir=../../lib/ansible/plugins/$$plugin -o rst $(PLUGIN_ARGS); \

-	done

+	$(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/ ../../lib/ansible/config/base.yml

+

+# For now, if we're building on devel, just build base docs.  In the future we'll want to build docs that

+# are the latest versions on galaxy (using a different antsibull-docs subcommand)

+plugins:

+	if expr "$(VERSION)" : '.*[.]dev[0-9]\+$$' &> /dev/null; then \

+		$(PLUGIN_FORMATTER) base -o rst $(PLUGIN_ARGS);\

+	else \

+		$(PLUGIN_FORMATTER) full -o rst $(PLUGIN_ARGS);\

+	fi

+

+# This only builds the plugin docs included with ansible-base

+base_plugins:

+	$(PLUGIN_FORMATTER) base -o rst $(PLUGIN_ARGS);\

 testing:

 	$(TESTING_FORMATTER)

@@ -10,26 +10,27 @@

       element.appendChild(para);

       document.write('</div>');

     }

-

-    // Create a banner if we're not the latest version

-    current_url = window.location.href;

-    if ((current_url.search("latest") > -1) || (current_url.search("/{{ latest_version }}/") > -1)) {

-     // no banner for latest release

-    } else if (current_url.search("devel") > -1) {

-      document.write('<div id="banner_id" class="admonition caution">');

-      para = document.createElement('p');

-      banner_text=document.createTextNode("You are reading the *devel* version of the Ansible documentation - most module documentation is currently missing as the modules have moved to collections. Until docs catches up to this change, use the version selection to the left if you want module documentation or the latest stable release version. The *devel* version is not guaranteed stable.");

-      para.appendChild(banner_text);

-      element = document.getElementById('banner_id');

-      element.appendChild(para);

-      document.write('</div>');

-    } else {

-      document.write('<div id="banner_id" class="admonition caution">');

-      para = document.createElement('p');

-      banner_text=document.createTextNode("You are reading an older version of the Ansible documentation. Use the version selection to the left if you want the latest stable released version.");

-      para.appendChild(banner_text);

-      element = document.getElementById('banner_id');

-      element.appendChild(para);

-      document.write('</div>');

-    }

+    {% if (not READTHEDOCS) and (available_versions is defined) %}

+      // Create a banner if we're not the latest version

+      current_url = window.location.href;

+      if ((current_url.search("latest") > -1) || (current_url.search("/{{ latest_version }}/") > -1)) {

+       // no banner for latest release

+      } else if (current_url.search("devel") > -1) {

+        document.write('<div id="banner_id" class="admonition caution">');

+        para = document.createElement('p');

+        banner_text=document.createTextNode("You are reading the *devel* version of the Ansible documentation - this version is not guaranteed stable. Use the version selection to the left if you want the latest stable released version.");

+        para.appendChild(banner_text);

+        element = document.getElementById('banner_id');

+        element.appendChild(para);

+        document.write('</div>');

+      } else {

+        document.write('<div id="banner_id" class="admonition caution">');

+        para = document.createElement('p');

+        banner_text=document.createTextNode("You are reading an older version of the Ansible documentation. Use the version selection to the left if you want the latest stable released version.");

+        para.appendChild(banner_text);

+        element = document.getElementById('banner_id');

+        element.appendChild(para);

+        document.write('</div>');

+      }

+    {% endif %}

   </script>

@@ -1,7 +1,7 @@

 <!--- Based on https://github.com/rtfd/sphinx_rtd_theme/pull/438/files -->

 {# Creates dropdown version selection in the top-left navigation. #}

 <div class="version">

-  {% if not READTHEDOCS %}

+  {% if (not READTHEDOCS) and (available_versions is defined) %}

     <div class="version-dropdown">

       <select class="version-list" id="version-list" onchange="javascript:location.href = this.value;">

         <script> x = document.getElementById("version-list"); </script>

new file mode 100644

@@ -0,0 +1,17 @@

+# We also need an example of modules hosted in Automation Hub

+# We'll likely move to data hosted in botmeta instead of a standalone file but

+# we'll need all of these same details.

+module:

+    purefa_user:

+        source: 'https://galaxy.ansible.com/'

+        fqcn: 'purestorage.flasharray'

+    purefa_vg:

+        source: 'https://galaxy.ansible.com/'

+        fqcn: 'purestorage.flasharray'

+    gcp_compute_firewall_info:

+        source: 'https://galaxy.ansible.com/'

+        fqcn: 'google.cloud'

+module_utils:

+    purefa:

+        source: 'https://galaxy.ansible.com/'

+        fqcn: 'purestorage.flasharray'

@@ -6,3 +6,4 @@ sphinx==2.1.2

 sphinx-notfound-page

 Pygments >= 2.4.0

 straight.plugin # Needed for hacking/build-ansible.py which is the backend build script

+antsibull >= 0.15.0

@@ -280,6 +280,10 @@ autoclass_content = 'both'

 intersphinx_mapping = {'python': ('https://docs.python.org/2/', (None, '../python2.inv')),

                        'python3': ('https://docs.python.org/3/', (None, '../python3.inv')),

                        'jinja2': ('http://jinja.palletsprojects.com/', (None, '../jinja2.inv')),

+                       'collections': ('https://docs.ansible.com/collections/',

+                                       (None, '../collections.inv',

+                                        'http://docs.testing.ansible.com/collections/objects.inv',

+                                        '../_collections_build/html/objects.inv')),

                        'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', (None, '../ansible_2_9.inv')),

                        'ansible_2_8': ('https://docs.ansible.com/ansible/2.8/', (None, '../ansible_2_8.inv')),

                        'ansible_2_7': ('https://docs.ansible.com/ansible/2.7/', (None, '../ansible_2_7.inv')),

@@ -74,7 +74,7 @@ Ansible releases a new major release of Ansible approximately three to four time

    :maxdepth: 1

    :caption: Reference & Appendices

-   ../modules/modules_by_category

+   collections/index

    reference_appendices/playbooks_keywords

    reference_appendices/common_return_values

    reference_appendices/config

@@ -10,7 +10,7 @@ Ansible Network modules extend the benefits of simple, powerful, agentless autom

 If you're new to Ansible, or new to using Ansible for network management, start with :ref:`network_getting_started`. If you are already familiar with network automation with Ansible, see :ref:`network_advanced`.

-For documentation on using a particular network module, consult the :ref:`list of all network modules<network_modules>`. Some network modules are maintained by the Ansible community - here's a list of :ref:`network modules maintained by the Ansible Network Team<network_supported>`.

+For documentation on using a particular network module, consult the :ref:`list of all network modules<network_modules>`. Network modules for various hardware are supported by different teams including the hardware vendors themselves, volunteers from the Ansible community, and the Ansible Network Team.

 .. toctree::

    :maxdepth: 3

@@ -47,11 +47,6 @@ Plugin List

 You can use ``ansible-doc -t become -l`` to see the list of available plugins.

 Use ``ansible-doc -t become <plugin name>`` to see specific documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    become/*

-

 .. seealso::

    :ref:`about_playbooks`

@@ -118,11 +118,6 @@ Plugin List

 You can use ``ansible-doc -t cache -l`` to see the list of available plugins.

 Use ``ansible-doc -t cache <plugin name>`` to see specific documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    cache/*

-

 .. seealso::

    :ref:`action_plugins`

@@ -79,12 +79,6 @@ Plugin list

 You can use ``ansible-doc -t callback -l`` to see the list of available plugins.

 Use ``ansible-doc -t callback <plugin name>`` to see specific documents and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    callback/*

-

-

 .. seealso::

    :ref:`action_plugins`

@@ -58,12 +58,6 @@ You can use ``ansible-doc -t connection -l`` to see the list of available plugin

 Use ``ansible-doc -t connection <plugin name>`` to see detailed documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    connection/*

-

-

 .. seealso::

    :ref:`Working with Playbooks<working_with_playbooks>`

@@ -162,11 +162,6 @@ Plugin List

 You can use ``ansible-doc -t inventory -l`` to see the list of available plugins.

 Use ``ansible-doc -t inventory <plugin name>`` to see plugin-specific documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    inventory/*

-

 .. seealso::

    :ref:`about_playbooks`

@@ -138,11 +138,6 @@ Plugin list

 You can use ``ansible-doc -t lookup -l`` to see the list of available plugins. Use ``ansible-doc -t lookup <plugin name>`` to see specific documents and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    lookup/*

-

 .. seealso::

    :ref:`about_playbooks`

@@ -33,11 +33,6 @@ In this case, you will also want to update the :ref:`ansible_shell_executable <a

 You can further control the settings for each plugin via other configuration options

 detailed in the plugin themselves (linked below).

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    shell/*

-

 .. seealso::

    :ref:`about_playbooks`

@@ -59,11 +59,6 @@ You can use ``ansible-doc -t strategy -l`` to see the list of available plugins.

 Use ``ansible-doc -t strategy <plugin name>`` to see plugin-specific specific documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    strategy/*

-

 .. seealso::

    :ref:`about_playbooks`

@@ -57,11 +57,6 @@ You can use ``ansible-doc -t vars -l`` to see the list of available plugins.

 Use ``ansible-doc -t vars <plugin name>`` to see specific plugin-specific documentation and examples.

-.. toctree:: :maxdepth: 1

-    :glob:

-

-    vars/*

-

 .. seealso::

    :ref:`action_plugins`

@@ -286,7 +286,7 @@ For more information, see `this systemd issue

 Become and network automation

 =============================

-As of version 2.6, Ansible supports ``become`` for privilege escalation (entering ``enable`` mode or privileged EXEC mode) on all :ref:`Ansible-maintained platforms<network_supported>` that support ``enable`` mode. Using ``become`` replaces the ``authorize`` and ``auth_pass`` options in a ``provider`` dictionary.

+As of version 2.6, Ansible supports ``become`` for privilege escalation (entering ``enable`` mode or privileged EXEC mode) on all Ansible-maintained network platforms that support ``enable`` mode. Using ``become`` replaces the ``authorize`` and ``auth_pass`` options in a ``provider`` dictionary.

 You must set the connection type to either ``connection: network_cli`` or ``connection: httpapi`` to use ``become`` for privilege escalation on network devices. Check the :ref:`platform_options` and :ref:`network_modules` documentation for details.

@@ -5,7 +5,8 @@

 Using collections

 *****************

-Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins.

+Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. As modules move from the core Ansible repository into collections, the module documentation will move to the `collections documentation page <https://docs.ansible.com/collections/>`_

+

 You can install and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.

 * For details on how to *develop* collections see :ref:`developing_collections`.

@@ -7,9 +7,8 @@ Working With Modules

    :maxdepth: 1

    modules_intro

-   ../reference_appendices/common_return_values

    modules_support

-   ../modules/modules_by_category

+   ../reference_appendices/common_return_values

 Ansible ships with a number of modules (called the 'module library')

deleted file mode 100644

@@ -1,48 +0,0 @@

-{# avoids rST "isn't included in any toctree" errors for module docs #}

-:orphan:

-

-{% if title %}

-.. _@{ title.lower() + '_' + plugin_type + 's' }@:

-{% else %}

-.. _@{ plugin_type + 's' }@:

-{% endif %}

-

-{% if title %}

-@{ title }@ @{ plugin_type + 's' }@

-@{ '`' * title | length }@````````

-{% else %}

-@{ plugin_type + 's' }@

-```````

-{% endif %}

-

-{% if blurb %}

-@{ blurb }@

-

-{% endif %}

-

-{% if category['_modules'] %}

-

-{% for module in category['_modules'] | sort %}

-  * :ref:`@{ module }@_@{ plugin_type }@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} 

-{% endfor %}

-{% endif %}

-

-{% for name, info in subcategories.items() | sort %}

-

-.. _@{ name.lower() + '_' + title.lower() + '_' + plugin_type + 's' }@:

-

-@{ name.title() }@

-@{ '-' * name | length }@

-

-

-

-{% for module in info['_modules'] | sort %}

-  * :ref:`@{ module }@_@{ plugin_type }@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} 

-{% endfor %}

-

-{% endfor %}

-

-.. note::

-    - **(D)**: This marks a module as deprecated, which means a module is kept for backwards compatibility but usage is discouraged.

-      The module documentation details page may explain more about this rationale.

-

deleted file mode 100644

@@ -1,36 +0,0 @@

-.. _@{ title.lower() + '_' + plugin_type + 's' }@:

-

-@{ title }@ @{ plugin_type }@

-@{ '`' * title | length }@````````

-

-{% if blurb %}

-@{ blurb }@

-

-{% endif %}

-.. toctree:: :maxdepth: 1

-{% if category['_modules'] %}

-

-{% for module in category['_modules'] | sort %}

-  @{ module }@{% if module_info[module]['deprecated'] %} **(D)**{% endif%}{% if module_info[module]['doc']['short_description'] %} -- @{ module_info[module]['doc']['short_description'] }@{% endif %} <plugins/@{ module_info[module]['primary_category'] }@/@{ module }@>

-{% endfor %}

-{% endif %}

-

-{% for name, info in subcategories.items() | sort %}

-

-.. _@{ name.lower() + '_' + title.lower() + '_' + plugin_type + 's' }@:

-

-@{ name.title() }@

-@{ '-' * name | length }@

-

-.. toctree:: :maxdepth: 1

-

-{% for module in info['_modules'] | sort %}

-  :ref:`@{ module }@_@{ plugin_type }@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} -- @{ module_info[module]['doc']['short_description'] }@

-{% endfor %}

-

-{% endfor %}

-

-.. note::

-    - **(D)**: This marks a module as deprecated, which means a module is kept for backwards compatibility but usage is discouraged.

-      The module documentation details page may explain more about this rationale.

-

deleted file mode 100644

@@ -1,45 +0,0 @@

-.. _@{ slug }@:

-

-{# avoids rST "isn't included in any toctree" errors for module index docs #}

-:orphan:

-

-**************************@{ '*' * maintainers | length }@

-Modules Maintained by the @{ maintainers }@

-**************************@{ '*' * maintainers | length }@

-

-.. contents::

-   :local:

-

-{% for category, data in subcategories.items() | sort %}

-

-{% if category.lower() %}

-.. _@{ category.lower() + '_' + slug.lower() + '_categories' }@:

-{% else %}

-.. _@{ slug.lower() + '_categories' }@:

-{% endif %}

-

-@{ category.title() }@

-@{ '=' * category | length }@

-

-{% for name, info in data.items() | sort %}

-

-{% if name.lower() %}

-.. _@{ name.lower() + '_' + category + '_' + slug.lower() + '_' + plugin_type + 's' }@:

-{% else %}

-.. _@{ slug.lower() + '_' + category }@:

-{% endif %}

-

-@{ name.title() }@

-@{ '-' * name | length }@

-

-{% for module in info['_modules'] | sort %}

-  * :ref:`@{ module }@_@{plugin_type}@`{% if module_info[module]['deprecated'] %} **(D)** {% endif%} 

-{% endfor %}

-

-{% endfor %}

-

-{% endfor %}

-

-.. note::

-    - **(D)**: This marks a module as deprecated, which means a module is kept for backwards compatibility but usage is discouraged.

-      The module documentation details page may explain more about this rationale.

deleted file mode 100644

@@ -1,442 +0,0 @@

-:source: @{ source }@

-

-{# avoids rST "isn't included in any toctree" errors for module docs #}

-{% if plugin_type == 'module' %}

-:orphan:

-{% endif %}

-

-.. _@{ module }@_@{ plugin_type }@:

-{% for alias in aliases %}

-.. _@{ alias }@_@{ plugin_type }@:

-{% endfor %}

-

-{% if short_description %}

-{%   set title = module + ' -- ' + short_description | rst_ify %}

-{% else %}

-{%   set title = module %}

-{% endif %}

-

-@{ title }@

-@{ '+' * title|length }@

-

-{% if version_added is defined and version_added != '' -%}

-.. versionadded:: @{ version_added | default('') }@

-{% endif %}

-

-.. contents::

-   :local:

-   :depth: 1

-

-{# ------------------------------------------

- #

- # Please note: this looks like a core dump

- # but it isn't one.

- #

- --------------------------------------------#}

-{% if deprecated is defined -%}

-

-

-DEPRECATED

-{# use unknown here? skip the fields? #}

-:Removed in Ansible: version: @{ deprecated['removed_in'] | default('') | string | rst_ify }@

-:Why: @{ deprecated['why'] | default('') | rst_ify }@

-:Alternative: @{ deprecated['alternative'] | default('') | rst_ify }@

-

-

-{% endif %}

-

-Synopsis

-{% if description -%}

-

-{%   for desc in description %}

-- @{ desc | rst_ify }@

-{%   endfor %}

-

-{% endif %}

-

-{% if aliases is defined -%}

-Aliases: @{ ','.join(aliases) }@

-{% endif %}

-

-{% if requirements -%}

-

-Requirements

-{%   if plugin_type == '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 %}

-

-{%   for req in requirements %}

-- @{ req | rst_ify }@

-{%   endfor %}

-

-{% endif %}

-

-{% if options -%}

-

-Parameters

-

-.. raw:: html

-

-    <table  border=0 cellpadding=0 class="documentation-table">

-        {# Pre-compute the nesting depth to allocate columns -#}

-        @{ to_kludge_ns('maxdepth', 1) -}@

-        {% for key, value in options|dictsort recursive -%}

-            @{ to_kludge_ns('maxdepth', [loop.depth, from_kludge_ns('maxdepth')] | max) -}@

-            {% if value.suboptions -%}

-                {% if value.suboptions.items -%}

-                    @{ loop(value.suboptions.items()) -}@

-                {% elif value.suboptions[0].items -%}

-                    @{ loop(value.suboptions[0].items()) -}@

-                {% endif -%}

-            {% endif -%}

-        {% endfor -%}

-        {# Header of the documentation -#}

-        <tr>

-            <th colspan="@{ from_kludge_ns('maxdepth') }@">Parameter</th>

-            <th>Choices/<font color="blue">Defaults</font></th>

-            {% if plugin_type != 'module' %}

-                <th>Configuration</th>

-            {% endif %}

-            <th width="100%">Comments</th>

-        </tr>

-        {% for key, value in options|dictsort recursive %}

-            <tr>

-                {# indentation based on nesting level #}

-                {% for i in range(1, loop.depth) %}

-                    <td class="elbow-placeholder"></td>

-                {% endfor %}

-                {# parameter name with required and/or introduced label #}

-                <td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">

-                    <div class="ansibleOptionAnchor" id="parameter-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}"></div>

-                    <b>@{ key }@</b>

-                    <a class="ansibleOptionLink" href="#parameter-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this option"></a>

-                    <div style="font-size: small">

-                        <span style="color: purple">@{ value.type | documented_type }@</span>

-                        {% if value.get('elements') %} / <span style="color: purple">elements=@{ value.elements | documented_type }@</span>{% endif %}

-                        {% if value.get('required', False) %} / <span style="color: red">required</span>{% endif %}

-                    </div>

-                    {% if value.version_added %}<div style="font-style: italic; font-size: small; color: darkgreen">added in @{value.version_added}@</div>{% endif %}

-                </td>

-                {# default / choices #}

-                <td>

-                    {# Turn boolean values in 'yes' and 'no' values #}

-                    {% if value.default is sameas true %}

-                        {% set _x = value.update({'default': 'yes'}) %}

-                    {% elif value.default is sameas false %}

-                        {% set _x = value.update({'default': 'no'}) %}

-                    {% endif %}

-                    {% if value.type == 'bool' %}

-                        {% set _x = value.update({'choices': ['no', 'yes']}) %}

-                    {% endif %}

-                    {# Show possible choices and highlight details #}

-                    {% if value.choices %}

-                        <ul style="margin: 0; padding: 0"><b>Choices:</b>

-                            {% for choice in value.choices %}

-                                {# Turn boolean values in 'yes' and 'no' values #}

-                                {% if choice is sameas true %}

-                                    {% set choice = 'yes' %}

-                                {% elif choice is sameas false %}

-                                    {% set choice = 'no' %}

-                                {% endif %}

-                                {% if (value.default is not list and value.default == choice) or (value.default is list and choice in value.default) %}

-                                    <li><div style="color: blue"><b>@{ choice | escape }@</b>&nbsp;&larr;</div></li>

-                                {% else %}

-                                    <li>@{ choice | escape }@</li>

-                                {% endif %}

-                            {% endfor %}

-                        </ul>

-                    {% endif %}

-                    {# Show default value, when multiple choice or no choices #}

-                    {% if value.default is defined and value.default not in value.choices %}

-                        <b>Default:</b><br/><div style="color: blue">@{ value.default | tojson | escape }@</div>

-                    {% endif %}

-                </td>

-                {# configuration #}

-                {% if plugin_type != 'module' %}

-                    <td>

-                        {% if 'ini' in value %}

-                            <div> ini entries:

-                                {% for ini in value.ini %}

-                                    <p>[@{ ini.section }@]<br>@{ ini.key }@ = @{ value.default | default('VALUE') }@</p>

-                                {% endfor %}

-                            </div>

-                        {% endif %}

-                        {% if 'env' in value %}

-                            {% for env in value.env %}

-                                <div>env:@{ env.name }@</div>

-                            {% endfor %}

-                        {% endif %}

-                        {% if 'vars' in value %}

-                            {% for myvar in value.vars %}

-                                <div>var: @{ myvar.name }@</div>

-                            {% endfor %}

-                        {% endif %}

-                    </td>

-                {% endif %}

-                {# description #}

-                <td>

-                    {% for desc in value.description %}

-                        <div>@{ desc | replace('\n', '\n    ') | html_ify }@</div>

-                    {% endfor %}

-                    {% if 'aliases' in value and value.aliases %}

-                        <div style="font-size: small; color: darkgreen"><br/>aliases: @{ value.aliases|join(', ') }@</div>

-                    {% endif %}

-                </td>

-            </tr>

-            {% if value.suboptions %}

-                {% if value.suboptions.items %}

-                    @{ loop(value.suboptions|dictsort) }@

-                {% elif value.suboptions[0].items %}

-                    @{ loop(value.suboptions[0]|dictsort) }@

-                {% endif %}

-            {% endif %}

-        {% endfor %}

-    </table>

-    <br/>

-

-{% endif %}

-

-{% if notes -%}

-Notes

-

-.. note::

-{%   for note in notes %}

-   - @{ note | rst_ify }@

-{%   endfor %}

-

-{% endif %}

-

-{% if seealso -%}

-See Also

-

-.. seealso::

-

-{% for item in seealso %}

-{%   if item.module is defined and item.description is defined %}

-   :ref:`@{ item.module }@_module`

-       @{ item.description | rst_ify }@

-{%   elif item.module is defined %}

-   :ref:`@{ item.module }@_module`

-      The official documentation on the **@{ item.module }@** module.

-{%   elif item.name is defined and item.link is defined and item.description is defined %}

-   `@{ item.name }@ <@{ item.link }@>`_

-       @{ item.description | rst_ify }@

-{%   elif item.ref is defined and item.description is defined %}

-   :ref:`@{ item.ref }@`

-       @{ item.description | rst_ify }@

-{%   endif %}

-{% endfor %}

-

-{% endif %}

-

-{% if examples or plainexamples -%}

-

-Examples

-

-.. code-block:: yaml+jinja

-

-{%   for example in examples %}

-{%     if example['description'] %}@{ example['description'] | indent(4, True) }@{% endif %}

-@{ example['code'] | escape | indent(4, True) }@

-{%   endfor %}

-{%   if plainexamples %}@{ plainexamples | indent(4, True) }@{% endif %}

-

-{% endif %}

-

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

-

-{% if returnfacts -%}

-

-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">

-        {# Pre-compute the nesting depth to allocate columns #}

-        @{ to_kludge_ns('maxdepth', 1) -}@

-        {% for key, value in returnfacts|dictsort recursive %}

-            @{ to_kludge_ns('maxdepth', [loop.depth, from_kludge_ns('maxdepth')] | max) -}@

-            {% if value.contains -%}

-                {% if value.contains.items -%}

-                    @{ loop(value.contains.items()) -}@

-                {% elif value.contains[0].items -%}

-                    @{ loop(value.contains[0].items()) -}@

-                {% endif -%}

-            {% endif -%}

-        {% endfor -%}

-        <tr>

-            <th colspan="@{ from_kludge_ns('maxdepth') }@">Fact</th>

-            <th>Returned</th>

-            <th width="100%">Description</th>

-        </tr>

-        {% for key, value in returnfacts|dictsort recursive %}