Adding upstream version 2.14.3.upstream/2.14.3upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

6 files changed, 679 insertions, 0 deletions

diff --git a/docs/templates/cli_rst.j2 b/docs/templates/cli_rst.j2
new file mode 100644
index 0000000..0e4c0f1
--- /dev/null
+++ b/docs/templates/cli_rst.j2
@@ -0,0 +1,161 @@
+:source: {{ cli }}.py
+
+{% set name = cli_name -%}
+{% set name_slug = cli_name -%}
+
+.. _{{name}}:
+
+{% set name_len = name|length + 0-%}
+{{ '=' * name_len }}
+{{name}}
+{{ '=' * name_len }}
+
+
+:strong:`{{short_desc|default('')}}`
+
+
+.. contents::
+   :local:
+   :depth: {{content_depth}}
+
+
+.. program:: {{cli_name}}
+
+Synopsis
+========
+
+.. code-block:: bash
+
+   {{ usage|replace('%prog', cli_name) }}
+
+
+Description
+===========
+
+
+{{ long_desc|default('', True)  }}
+
+{% if options %}
+Common Options
+==============
+
+
+{% for option in options|sort(attribute='options') if option.options %}
+
+.. option:: {% for switch in option['options'] %}{{switch}}{% if option['arg'] %} <{{option['arg']}}>{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}
+
+   {{ option['desc'] }}
+{% endfor %}
+{% endif %}
+
+{% if arguments %}
+ARGUMENTS
+=========
+
+.. program:: {{cli_name}}
+
+{% for arg in arguments %}
+.. option:: {{ arg }}
+
+   {{ (arguments[arg]|default(' '))}}
+
+{% endfor %}
+{% endif %}
+
+{% if actions %}
+Actions
+=======
+
+{% for action in actions %}
+
+.. program:: {{cli_name}} {{action}}
+.. _{{cli_name|replace('-','_')}}_{{action}}:
+
+{{ action}}
+{{ '-' * action|length}}
+
+{{ (actions[action]['desc']|default(' '))}}
+
+{% if actions[action]['options'] %}
+
+
+{% for option in actions[action]['options']|sort(attribute='options') %}
+.. option:: {% for switch in option['options'] if switch in actions[action]['option_names'] %}{{switch}} {% if option['arg'] %} <{{option['arg']}}>{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}
+
+   {{ (option['desc']) }}
+{% endfor %}
+{% endif %}
+
+{% for sub_action in actions[action]['actions'] %}
+
+
+.. program:: {{cli_name}} {{action}} {{sub_action}}
+.. _{{cli_name|replace('-','_')}}_{{action}}_{{sub_action}}:
+
+{{ action + " " + sub_action }}
+{{ '+' * (action|length + sub_action|length + 1) }}
+
+{{ (actions[action]['actions'][sub_action]['desc']|default(' '))}}
+
+{% if actions[action]['actions'][sub_action]['options'] %}
+
+
+{% for option in actions[action]['actions'][sub_action]['options']|sort(attribute='options') %}
+.. option:: {% for switch in option['options'] if switch in actions[action]['actions'][sub_action]['option_names'] %}{{switch}} {% if option['arg'] %} <{{option['arg']}}>{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}
+
+   {{ (option['desc']) }}
+{% endfor %}
+{% endif %}
+
+{% endfor %}
+
+{% endfor %}
+.. program:: {{cli_name}}
+{% endif %}
+
+Environment
+===========
+
+The following environment variables may be specified.
+
+{% if inventory %}
+:envvar:`ANSIBLE_INVENTORY`  -- Override the default ansible inventory file
+
+{% endif %}
+{% if library %}
+:envvar:`ANSIBLE_LIBRARY` -- Override the default ansible module library path
+
+{% endif %}
+:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
+
+Many more are available for most options in ansible.cfg
+
+
+Files
+=====
+
+{% if inventory %}
+:file:`/etc/ansible/hosts` -- Default inventory file
+
+{% endif %}
+:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
+
+:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
+
+Author
+======
+
+Ansible was originally written by Michael DeHaan.
+
+See the `AUTHORS` file for a complete list of contributors.
+
+
+License
+=======
+
+Ansible is released under the terms of the GPLv3+ License.
+
+See also
+========
+
+{% for other in cli_bin_name_list|sort %}:manpage:`{{other}}(1)`,  {% endfor %}
diff --git a/docs/templates/collections_galaxy_meta.rst.j2 b/docs/templates/collections_galaxy_meta.rst.j2
new file mode 100644
index 0000000..09d11c3
--- /dev/null
+++ b/docs/templates/collections_galaxy_meta.rst.j2
@@ -0,0 +1,98 @@
+.. _collections_galaxy_meta:
+
+************************************
+Collection Galaxy metadata structure
+************************************
+
+A key component of an Ansible collection is the ``galaxy.yml`` file placed in the root directory of a collection. This
+file contains the metadata of the collection that is used to generate a collection artifact.
+
+Structure
+=========
+
+The ``galaxy.yml`` file must contain the following keys in valid YAML:
+
+
+.. rst-class:: documentation-table
+
+.. list-table::
+    :header-rows: 1
+    :widths: auto
+
+    * - Key
+      - Comment
+
+{%- for entry in options %}
+
+
+    * - .. rst-class:: value-name
+
+        @{ entry.key }@ |br|
+
+        .. rst-class:: value-type
+
+        @{ entry.type | documented_type }@ |_|
+
+        {% if entry.get('required', False) -%}
+        .. rst-class:: value-separator
+
+        / |_|
+
+        .. rst-class:: value-required
+
+        required
+        {%- endif %}
+
+        {% if 'version_added' in entry -%}
+
+        .. rst-class:: value-added-in
+
+        |br| version_added: @{ entry.version_added }@
+
+        |_|
+
+        {%- endif %}
+
+      - {% for desc in entry.description -%}
+        @{ desc | trim | rst_ify }@
+
+        {% endfor -%}
+{%- endfor %}
+
+
+Examples
+========
+
+.. code-block:: yaml
+
+    namespace: "namespace_name"
+    name: "collection_name"
+    version: "1.0.12"
+    readme: "README.md"
+    authors:
+        - "Author1"
+        - "Author2 (https://author2.example.com)"
+        - "Author3 <author3@example.com>"
+    dependencies:
+        "other_namespace.collection1": ">=1.0.0"
+        "other_namespace.collection2": ">=2.0.0,<3.0.0"
+        "anderson55.my_collection": "*"    # note: "*" selects the highest version available
+    license:
+        - "MIT"
+    tags:
+        - demo
+        - collection
+    repository: "https://www.github.com/my_org/my_collection"
+
+.. seealso::
+
+  :ref:`developing_collections`
+       Develop or modify a collection.
+  :ref:`developing_modules_general`
+       Learn about how to write Ansible modules
+  :ref:`collections`
+       Learn how to install and use collections.
+  `Mailing List <https://groups.google.com/group/ansible-devel>`_
+       The development mailing list
+  `irc.libera.chat <https://libera.chat/>`_
+       #ansible IRC chat channel
diff --git a/docs/templates/config.rst.j2 b/docs/templates/config.rst.j2
new file mode 100644
index 0000000..34b2b84
--- /dev/null
+++ b/docs/templates/config.rst.j2
@@ -0,0 +1,242 @@
+.. _ansible_configuration_settings:
+
+{%   set name = 'Ansible Configuration Settings' -%}
+{%   set name_slug = 'config' -%}
+
+{%   set name_len = name|length + 0-%}
+{{ '=' * name_len }}
+{{name}}
+{{ '=' * name_len }}
+
+Ansible supports several sources for configuring its behavior, including an ini file named ``ansible.cfg``, environment variables, command-line options, playbook keywords, and variables. See :ref:`general_precedence_rules` for details on the relative precedence of each source.
+
+The ``ansible-config`` utility allows users to see all the configuration settings available, their defaults, how to set them and
+where their current value comes from. See :ref:`ansible-config` for more information.
+
+.. _ansible_configuration_settings_locations:
+
+The configuration file
+======================
+
+Changes can be made and used in a configuration file which will be searched for in the following order:
+
+ * ``ANSIBLE_CONFIG`` (environment variable if set)
+ * ``ansible.cfg`` (in the current directory)
+ * ``~/.ansible.cfg`` (in the home directory)
+ * ``/etc/ansible/ansible.cfg``
+
+Ansible will process the above list and use the first file found, all others are ignored.
+
+.. note::
+
+   The configuration file is one variant of an INI format.
+   Both the hash sign (``#``) and semicolon (``;``) are allowed as
+   comment markers when the comment starts the line.
+   However, if the comment is inline with regular values,
+   only the semicolon is allowed to introduce the comment.
+   For instance::
+
+        # some basic default values...
+        inventory = /etc/ansible/hosts  ; This points to the file that lists your hosts
+
+
+.. _generating_ansible.cfg:
+
+Generating a sample ``ansible.cfg`` file
+-----------------------------------------
+
+You can generate a fully commented-out example ``ansible.cfg`` file, for example::
+
+   $ ansible-config init --disabled > ansible.cfg
+
+You can also have a more complete file that includes existing plugins::
+
+   $ ansible-config init --disabled -t all > ansible.cfg
+
+You can use these as starting points to create your own ``ansible.cfg`` file.
+
+.. _cfg_in_world_writable_dir:
+
+Avoiding security risks with ``ansible.cfg`` in the current directory
+---------------------------------------------------------------------
+
+
+If Ansible were to load ``ansible.cfg`` from a world-writable current working
+directory, it would create a serious security risk. Another user could place
+their own config file there, designed to make Ansible run malicious code both
+locally and remotely, possibly with elevated privileges. For this reason,
+Ansible will not automatically load a config file from the current working
+directory if the directory is world-writable.
+
+If you depend on using Ansible with a config file in the current working
+directory, the best way to avoid this problem is to restrict access to your
+Ansible directories to particular user(s) and/or group(s). If your Ansible
+directories live on a filesystem which has to emulate Unix permissions, like
+Vagrant or Windows Subsystem for Linux (WSL), you may, at first, not know how
+you can fix this as ``chmod``, ``chown``, and ``chgrp`` might not work there.
+In most of those cases, the correct fix is to modify the mount options of the
+filesystem so the files and directories are readable and writable by the users
+and groups running Ansible but closed to others.  For more details on the
+correct settings, see:
+
+* for Vagrant, the `Vagrant documentation <https://www.vagrantup.com/docs/synced-folders/>`_ covers synced folder permissions.
+* for WSL, the `WSL docs <https://docs.microsoft.com/en-us/windows/wsl/wsl-config#set-wsl-launch-settings>`_
+  and this `Microsoft blog post <https://blogs.msdn.microsoft.com/commandline/2018/01/12/chmod-chown-wsl-improvements/>`_ cover mount options.
+
+If you absolutely depend on storing your Ansible config in a world-writable current
+working directory, you can explicitly specify the config file via the
+:envvar:`ANSIBLE_CONFIG` environment variable. Please take
+appropriate steps to mitigate the security concerns above before doing so.
+
+
+Relative paths for configuration
+--------------------------------
+
+You can specify a relative path for many configuration options. In most of
+those cases the path used will be relative to the ``ansible.cfg`` file used
+for the current execution. If you need a path relative to your current working
+directory (CWD) you can use the ``{%raw%}{{CWD}}{%endraw%}`` macro to specify
+it. We do not recommend this approach, as using your CWD as the root of
+relative paths can be a security risk. For example:
+``cd /tmp; secureinfo=./newrootpassword ansible-playbook ~/safestuff/change_root_pwd.yml``.
+
+
+Common Options
+==============
+
+This is a copy of the options available from our release, your local install might have extra options due to additional plugins,
+you can use the command line utility mentioned above (`ansible-config`) to browse through those.
+
+{% if config_options %}
+
+
+{%   for config_option in config_options|sort %}
+{%     set config_len = config_option|length -%}
+{%     set config = config_options[config_option] %}
+.. _{{config_option}}:
+
+{{config_option}}
+{{ '-' * config_len }}
+
+{%     if config['description'] and config['description'] != [''] %}
+{%       if config['description'] != ['TODO: write it'] %}
+:Description: {{' '.join(config['description'])}}
+{%       endif %}
+{%     endif %}
+{%     if config['type'] %}
+:Type: {{config['type']}}
+{%     endif %}
+{%     if 'default' in config %}
+:Default: ``{{config['default']}}``
+{%     endif %}
+{%     if config.get('choices', False) %}
+:Choices:
+{%       if config['choices'] is mapping %}
+{%         for key in config['choices'].keys() %}
+    - :{{key}}: {{ config['choices'][key] }}
+{%         endfor %}
+{%       else %}
+{%         for key in config['choices'] %}
+    - {{key}}
+{%         endfor %}
+{%       endif %}
+{%     endif %}
+{%     if config['version_added'] %}
+:Version Added: {{config['version_added']}}
+{%     endif %}
+{%     if config.get('ini', False) %}
+:Ini:
+{%       for ini_map in config['ini']|sort(attribute='section') %}
+     {% if config['ini']|length > 1 %}- {% endif %}:Section: [{{ini_map['section']}}]
+     {% if config['ini']|length > 1 %}  {% endif %}:Key: {{ini_map['key']}}
+{%         if ini_map['version_added'] %}
+       :Version Added: {{ini_map['version_added']}}
+{%         endif %}
+{%         if ini_map['deprecated'] %}
+       :Deprecated in: {{ini_map['deprecated']['version']}}
+       :Deprecated detail: {{ini_map['deprecated']['why']}}
+{%           if ini_map['deprecated']['alternatives'] %}
+       :Deprecated alternatives: {{ini_map['deprecated']['alternatives']}}
+{%           endif %}
+{%         endif %}
+{%       endfor %}
+{%     endif %}
+{%     if config.get('env', False) %}
+:Environment:
+{%       for env_var_map in config['env']|sort(attribute='name') %}
+     {% if config['env']|length > 1 %}- {% endif %}:Variable: :envvar:`{{env_var_map['name']}}`
+{%         if env_var_map['version_added'] %}
+       :Version Added: {{env_var_map['version_added']}}
+{%         endif %}
+{%         if env_var_map['deprecated'] %}
+       :Deprecated in: {{env_var_map['deprecated']['version']}}
+       :Deprecated detail: {{env_var_map['deprecated']['why']}}
+{%           if env_var_map['deprecated']['alternatives'] %}
+       :Deprecated alternatives: {{env_var_map['deprecated']['alternatives']}}
+{%           endif %}
+{%         endif %}
+{%       endfor %}
+{%     endif %}
+{%     if config.get('vars', False) %}
+:Variables:
+{%       for a_var in config['vars']|sort(attribute='name') %}
+     {% if config['vars']|length > 1 %}- {%endif%}:name: `{{a_var['name']}}`
+{%       if a_var['version_added'] %}
+       :Version Added: {{a_var['version_added']}}
+{%       endif %}
+{%         if a_var['deprecated'] %}
+       :Deprecated in: {{a_var['deprecated']['version']}}
+       :Deprecated detail: {{a_Var['deprecated']['why']}}
+{%           if a_var['deprecated']['alternatives'] %}
+       :Deprecated alternatives: {{a_var['deprecated']['alternatives']}}
+{%           endif %}
+{%         endif %}
+{%       endfor %}
+{%     endif %}
+{%     if config['deprecated'] %}
+:Deprecated in: {{config['deprecated']['version']}}
+:Deprecated detail: {{config['deprecated']['why']}}
+{%       if config['deprecated']['alternatives'] %}
+:Deprecated alternatives: {{config['deprecated']['alternatives']}}
+{%       endif %}
+{%     endif %}
+
+{%   endfor %}
+
+Environment Variables
+=====================
+
+.. envvar:: ANSIBLE_CONFIG
+
+
+    Override the default ansible config file
+
+
+{%   for config_option in config_options %}
+{%     for env_var_map in config_options[config_option]['env'] %}
+.. envvar:: {{env_var_map['name']}}
+
+{%       if config_options[config_option]['description']  and config_options[config_option]['description'] != [''] %}
+{%         if config_options[config_option]['description'] != ['TODO: write it'] %}
+    {{ ''.join(config_options[config_option]['description']) }}
+{%         endif %}
+{%       endif %}
+
+    See also :ref:`{{config_option}} <{{config_option}}>`
+
+{%       if env_var_map['version_added'] %}
+    :Version Added: {{env_var_map['version_added']}}
+{%       endif %}
+{%       if env_var_map['deprecated'] %}
+    :Deprecated in: {{env_var_map['deprecated']['version']}}
+    :Deprecated detail: {{env_var_map['deprecated']['why']}}
+{%         if env_var_map['deprecated']['alternatives'] %}
+    :Deprecated alternatives: {{env_var_map['deprecated']['alternatives']}}
+{%         endif %}
+{%       endif %}
+
+{%     endfor %}
+
+{%   endfor %}
+
+{% endif %}
diff --git a/docs/templates/man.j2 b/docs/templates/man.j2
new file mode 100644
index 0000000..8bd3644
--- /dev/null
+++ b/docs/templates/man.j2
@@ -0,0 +1,128 @@
+{% set name = ('ansible' if cli == 'adhoc' else 'ansible-%s' % cli) -%}
+{{name}}
+{{ '=' * ( name|length|int ) }}
+
+{{ '-' * ( short_desc|default('')|string|length|int ) }}
+{{short_desc|default('')}}
+{{ '-' * ( short_desc|default('')|string|length|int ) }}
+
+:Version:        Ansible %VERSION%
+:Manual section: 1
+:Manual group:   System administration commands
+
+
+
+SYNOPSIS
+--------
+{{ usage|replace('%prog', name) }}
+
+
+DESCRIPTION
+-----------
+{{ long_desc|default('', True)|wordwrap }}
+
+{% if options %}
+COMMON OPTIONS
+--------------
+{% for option in options|sort(attribute='options') %}
+{% for switch in option['options'] %}**{{switch}}**{% if option['arg'] %} '{{option['arg']}}'{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}
+
+  {{ option['desc'] }}
+{% endfor %}
+{% endif %}
+
+{% if arguments %}
+ARGUMENTS
+---------
+
+{% for arg in arguments %}
+{{ arg }}
+
+{{ (arguments[arg]|default(' '))|wordwrap }}
+
+{% endfor %}
+{% endif %}
+
+{% if actions %}
+ACTIONS
+-------
+{% for action in actions %}
+**{{ action }}**
+  {{ (actions[action]['desc']|default(' ')) |replace('\n', ' ')}}
+
+{% if actions[action]['options'] %}
+{% for option in actions[action]['options']|sort(attribute='options') %}
+{% for switch in option['options'] if switch in actions[action]['option_names'] %}  **{{switch}}**{% if option['arg'] %} '{{option['arg']}}'{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}
+
+        {{ (option['desc']) }}
+{% endfor %}
+{% endif %}
+{% endfor %}
+{% endif %}
+
+
+{% if inventory %}
+INVENTORY
+---------
+
+Ansible stores the hosts it can potentially operate on in an inventory.
+This can be an YAML file, ini-like file, a script, directory, list, etc.
+For additional options, see the documentation on https://docs.ansible.com/.
+
+{% endif %}
+ENVIRONMENT
+-----------
+
+The following environment variables may be specified.
+
+{% if inventory %}
+ANSIBLE_INVENTORY  -- Override the default ansible inventory sources
+
+{% endif %}
+{% if library %}
+ANSIBLE_LIBRARY -- Override the default ansible module library path
+
+{% endif %}
+ANSIBLE_CONFIG -- Specify override location for the ansible config file
+
+Many more are available for most options in ansible.cfg
+
+For a full list check https://docs.ansible.com/. or use the `ansible-config` command.
+
+FILES
+-----
+
+{% if inventory %}
+/etc/ansible/hosts -- Default inventory file
+
+{% endif %}
+/etc/ansible/ansible.cfg -- Config file, used if present
+
+~/.ansible.cfg -- User config file, overrides the default config if present
+
+./ansible.cfg -- Local config file (in current working directory) assumed to be 'project specific' and overrides the rest if present.
+
+As mentioned above, the ANSIBLE_CONFIG environment variable will override all others.
+
+AUTHOR
+------
+
+Ansible was originally written by Michael DeHaan.
+
+
+COPYRIGHT
+---------
+
+Copyright © 2018 Red Hat, Inc | Ansible.
+Ansible is released under the terms of the GPLv3 license.
+
+
+SEE ALSO
+--------
+
+{% for other in cli_list|sort %}{% if other != cli %}**ansible{% if other != 'adhoc' %}-{{other}}{% endif %}** (1){% if not loop.last %}, {% endif %}{% endif %}{% endfor %}
+
+Extensive documentation is available in the documentation site:
+<https://docs.ansible.com>.
+IRC and mailing list info can be found in file CONTRIBUTING.md,
+available in: <https://github.com/ansible/ansible>
diff --git a/docs/templates/modules_by_category.rst.j2 b/docs/templates/modules_by_category.rst.j2
new file mode 100644
index 0000000..7763528
--- /dev/null
+++ b/docs/templates/modules_by_category.rst.j2
@@ -0,0 +1,17 @@
+.. _modules_by_category:
+
+{# avoids rST "isn't included in any toctree" errors for module index docs #}
+:orphan:
+
+Module Index
+============
+
+
+.. toctree:: :maxdepth: 1
+
+{% for name in categories %}
+{# strip out empty category names as a result flattening the dir structure #}
+{% if name %}
+   list_of_@{ name }@_modules
+{% endif %}
+{% endfor %}
diff --git a/docs/templates/playbooks_keywords.rst.j2 b/docs/templates/playbooks_keywords.rst.j2
new file mode 100644
index 0000000..8d42267
--- /dev/null
+++ b/docs/templates/playbooks_keywords.rst.j2
@@ -0,0 +1,33 @@
+.. _playbook_keywords:
+
+Playbook Keywords
+=================
+
+These are the keywords available on common playbook objects. Keywords are one of several sources for configuring Ansible behavior. See :ref:`general_precedence_rules` for details on the relative precedence of each source.
+
+
+.. note:: Please note:
+
+    * Aliases for the directives are not reflected here, nor are mutable one. For example,
+      :term:`action` in task can be substituted by the name of any Ansible module.
+    * The keywords do not have ``version_added`` information at this time
+    * Some keywords set defaults for the objects inside of them rather than for the objects
+      themselves
+
+
+.. contents::
+   :local:
+   :depth: 1
+
+{% for name in playbook_class_names %}
+
+{{ name }}
+{{ '-' * name|length }}
+{#.. glossary::#}
+
+{% for attribute in pb_keywords[name]|sort %}
+    {{ attribute }}
+        {{ pb_keywords[name][attribute] |indent(8) }}
+
+{% endfor %}
+{% endfor %}