diff options
Diffstat (limited to 'docs/templates')
| -rw-r--r-- | docs/templates/cli_rst.j2 | 161 | ||||
| -rw-r--r-- | docs/templates/collections_galaxy_meta.rst.j2 | 98 | ||||
| -rw-r--r-- | docs/templates/config.rst.j2 | 227 | ||||
| -rw-r--r-- | docs/templates/man.j2 | 128 | ||||
| -rw-r--r-- | docs/templates/modules_by_category.rst.j2 | 17 | ||||
| -rw-r--r-- | docs/templates/playbooks_keywords.rst.j2 | 33 |
6 files changed, 664 insertions, 0 deletions
diff --git a/docs/templates/cli_rst.j2 b/docs/templates/cli_rst.j2 new file mode 100644 index 00000000..0e4c0f16 --- /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 00000000..f7ca6670 --- /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.freenode.net <http://irc.freenode.net>`_ + #ansible IRC chat channel diff --git a/docs/templates/config.rst.j2 b/docs/templates/config.rst.j2 new file mode 100644 index 00000000..35a54017 --- /dev/null +++ b/docs/templates/config.rst.j2 @@ -0,0 +1,227 @@ +.. _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 + + +.. _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 00000000..8bd3644c --- /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 00000000..77635284 --- /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 00000000..4ce19aaa --- /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 %} |