diff --git a/docs/docsite/rst/community/community.rst b/docs/docsite/rst/community/community.rst index 5a62d20a769..5dadb7bc9ef 100644 --- a/docs/docsite/rst/community/community.rst +++ b/docs/docsite/rst/community/community.rst @@ -1,3 +1,5 @@ +:orphan: + Community Information & Contributing ```````````````````````````````````` diff --git a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst index e28f05fc52c..9538066e680 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst @@ -33,7 +33,7 @@ The following checklist items are important guidelines for people who want to c 'supported_by': 'community', 'metadata_version': '1.1'} -Read the complete :ref:`module metadata specification ` for more information. +Read the complete :ref:`module metadata specification ` for more information. * Documentation: Make sure it exists * Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts. This documentation is not meant to teach a total novice, but it also should not be reserved for the Illuminati (hard balance). @@ -100,7 +100,7 @@ Read the complete :ref:`module metadata specification ` * Do not use wildcards for importing other python modules (ex: ``from ansible.module_utils.basic import *``). This used to be required for code imported from ``ansible.module_utils`` but, from Ansible-2.1 onwards, it's just an outdated and bad practice. * The module must have a `main` function that wraps the normal execution. * Call your :func:`main` from a conditional so that it would be possible to - import them into unittests in the future example + import them into unit tests in the future example .. code-block:: python @@ -119,8 +119,8 @@ Read the complete :ref:`module metadata specification ` fields of a dictionary and return the dictionary. * When fetching URLs, please use either fetch_url or open_url from ansible.module_utils.urls rather than urllib2; urllib2 does not natively verify TLS certificates and so is insecure for https. -* facts modules must return facts in the ansible_facts field of the result - dictionary. :ref:`module_provided_facts` +* facts modules must return facts in the ansible_facts field of the :ref:`result + dictionary`. * modules that are purely about fact gathering need to implement check_mode. they should not cause any changes anyway so it should be as simple as adding check_mode=True when instantiating AnsibleModule. (The reason is that diff --git a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst index cd50b98d97e..420c1a3d4b7 100644 --- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst @@ -517,7 +517,7 @@ Why pass args over stdin? Passing arguments via stdin was chosen for the following reasons: -* When combined with :ref:`pipelining`, this keeps the module's arguments from +* When combined with :ref:`ANSIBLE_PIPELINING`, this keeps the module's arguments from temporarily being saved onto disk on the remote machine. This makes it harder (but not impossible) for a malicious user on the remote machine to steal any sensitive information that may be present in the arguments. diff --git a/docs/docsite/rst/dev_guide/testing_running_locally.rst b/docs/docsite/rst/dev_guide/testing_running_locally.rst index 2f5ac0ee2a7..43877097752 100644 --- a/docs/docsite/rst/dev_guide/testing_running_locally.rst +++ b/docs/docsite/rst/dev_guide/testing_running_locally.rst @@ -1,3 +1,5 @@ +.. _testing_running_locally: + *************** Testing Ansible *************** diff --git a/docs/docsite/rst/dev_guide/testing_units.rst b/docs/docsite/rst/dev_guide/testing_units.rst index 0290514be55..a7df079d98f 100644 --- a/docs/docsite/rst/dev_guide/testing_units.rst +++ b/docs/docsite/rst/dev_guide/testing_units.rst @@ -164,7 +164,7 @@ See `eos_banner test for a practical example. If you are simulating APIs you may find that python placebo is useful. See -doc:`testing_units_modules` for more information. +:ref:`testing_units_modules` for more information. Code Coverage For New or Updated Unit Tests @@ -189,13 +189,13 @@ Reports can be generated in several different formats: * ``ansible-test coverage xml`` - XML report. To clear data between test runs, use the ``ansible-test coverage erase`` command. See -:doc:`testing_units_running_locally` for more information about generating coverage +:ref:`testing_running_locally` for more information about generating coverage reports. .. seealso:: - :doc:`testing_units_modules` + :ref:`testing_units_modules` Special considerations for unit testing modules :doc:`testing_running_locally` Running tests locally including gathering and reporting coverage data diff --git a/docs/docsite/rst/dev_guide/testing_units_modules.rst b/docs/docsite/rst/dev_guide/testing_units_modules.rst index 490a271f0e5..91bc14ddf02 100644 --- a/docs/docsite/rst/dev_guide/testing_units_modules.rst +++ b/docs/docsite/rst/dev_guide/testing_units_modules.rst @@ -1,3 +1,5 @@ +.. _testing_units_modules: + **************************** Unit Testing Ansible Modules **************************** diff --git a/docs/docsite/rst/installation_guide/intro_configuration.rst b/docs/docsite/rst/installation_guide/intro_configuration.rst index e68b0d62507..37977b03731 100644 --- a/docs/docsite/rst/installation_guide/intro_configuration.rst +++ b/docs/docsite/rst/installation_guide/intro_configuration.rst @@ -31,7 +31,7 @@ default settings in Ansible. An `example file is available on Github `_. -For more details and a full listing of available configurations go to :ref:`configuration_settings`. Starting with Ansible version 2.4, you can use the :ref:`ansible-config` command line utility to list your available options and inspect the current values. +For more details and a full listing of available configurations go to :ref:`configuration_settings`. Starting with Ansible version 2.4, you can use the :ref:`ansible-config` command line utility to list your available options and inspect the current values. For in-depth details, see :ref:`ansible_configuration_settings`. diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 76c0d551731..cf8f401c0a8 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -68,7 +68,7 @@ later). * If you have SELinux enabled on remote nodes, you will also want to install libselinux-python on them before using any copy/file/template related functions in Ansible. You - can use the :ref:`yum` or :ref`dnf` module in Ansible to install this package on remote systems + can use the :ref:`yum module` or :ref:`dnf module` in Ansible to install this package on remote systems that do not have it. * By default, Ansible uses the python interpreter located at :file:`/usr/bin/python` to run its @@ -77,14 +77,14 @@ later). "module_stdout": "/bin/sh: /usr/bin/python: No such file or directory\r\n" - you can either set the :ref:`ansible_python_interpreter` inventory variable (see + you can either set the :ref:`ansible_python_interpreter` inventory variable (see :ref:`inventory`) to point at your interpreter or you can install a Python 2 interpreter for - modules to use. You will still need to set :ref:`ansible_python_interpreter` if the Python + modules to use. You will still need to set :ref:`ansible_python_interpreter` if the Python 2 interpreter is not installed to :command:`/usr/bin/python`. * Ansible's "raw" module (for executing commands in a quick and dirty way) and the script module don't even need Python installed. So technically, you can use Ansible to install a compatible - version of Python using the :ref:`raw` module, which then allows you to use everything else. + version of Python using the :ref:`raw module`, which then allows you to use everything else. For example, if you need to bootstrap Python 2 onto a RHEL-based system, you can install it via diff --git a/docs/docsite/rst/network/user_guide/shared_snippets/SSH_warning.rst b/docs/docsite/rst/network/user_guide/shared_snippets/SSH_warning.rst index 27424f57776..e7d4bdef568 100644 --- a/docs/docsite/rst/network/user_guide/shared_snippets/SSH_warning.rst +++ b/docs/docsite/rst/network/user_guide/shared_snippets/SSH_warning.rst @@ -1,2 +1,4 @@ +:orphan: + .. warning:: Never store passwords in plain text. We recommend using SSH keys to authenticate SSH connections. Ansible supports ssh-agent to manage your SSH keys. If you must use passwords to authenticate SSH connections, we recommend encrypting them with :ref:`Ansible Vault `. diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index cdba361764f..468ab4e37bc 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -1,15 +1,13 @@ .. contents:: Topics - Connection Plugins ------------------ Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. -By default, Ansible ships with several plugins. The most commonly used are the 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection types. All of these can be used in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines. - -The basics of these connection types are covered in the :ref:`getting started` section. +By default, Ansible ships with several plugins. The most commonly used are the :ref:`paramiko SSH`, native ssh (just called :ref:`ssh`), and :ref:`local` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. +The basics of these connection types are covered in the :ref:`getting started` section. .. _ssh_plugins: @@ -26,28 +24,26 @@ Enabling Connection Plugins You can extend Ansible to support other transports (such as SNMP or message bus) by dropping a custom plugin into the ``connection_plugins`` directory. - .. _using_connection: Using Connection Plugins ++++++++++++++++++++++++ -The transport can be changed via :ref:`configuration`, in the command line (``-c``, ``--connection``), as a :ref:`keyword`) -in your play, or by setting a :ref:`variable`, most often in your inventory. +The transport can be changed via :ref:`configuration`, at the command line (``-c``, ``--connection``), as a :ref:`keyword ` in your play, or by setting a :ref:`variable`, most often in your inventory. For example, for Windows machines you might want to use the :doc:`winrm` plugin. -Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory hostname` and defaults to find the target host. +Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory hostname` and defaults to find the target host. Plugins are self-documenting. Each plugin should document its configuration options. The following are connection variables common to most connection plugins: -:ref:`ansible_host` - The name of the host to connect to, if different from the :ref:`inventory hostname`. -:ref:`ansible_port` - The ssh port number, for :doc:`ssh ` and :doc:`paramiko_ssh ` it defaults to 22. -:ref:`ansible_user` +:ref:`ansible_host` + The name of the host to connect to, if different from the :ref:`inventory ` hostname. +:ref:`ansible_port` + The ssh port number, for :ref:`ssh ` and :ref:`paramiko_ssh ` it defaults to 22. +:ref:`ansible_user` The default user name to use for log in. Most plugins default to the 'current user running Ansible'. -Each plugin might also have a specific version of a variable that overrides the general version. For example, :ref:`ansible_ssh_host` for the :doc:`ssh ` plugin. +Each plugin might also have a specific version of a variable that overrides the general version. For example, ``ansible_ssh_host`` for the :ref:`ssh ` plugin. .. _connection_plugin_list: diff --git a/docs/docsite/rst/plugins/shell.rst b/docs/docsite/rst/plugins/shell.rst index 714730393fe..708bfe79d09 100644 --- a/docs/docsite/rst/plugins/shell.rst +++ b/docs/docsite/rst/plugins/shell.rst @@ -4,7 +4,7 @@ Shell Plugins ------------- Shell plugins work to ensure that the basic commands Ansible runs are properly formatted to work with -the target machine and allow the user to configure certain behaviours related to how Ansible executes tasks. +the target machine and allow the user to configure certain behaviors related to how Ansible executes tasks. .. _enabling_shell: @@ -23,8 +23,8 @@ Using Shell Plugins +++++++++++++++++++ In addition to the default configuration settings in :ref:`ansible_configuration_settings`, you can use -a 'connection variable' :ref:`ansible_shell_type` to select the plugin to use. -In this case, you will also want to update the :ref:`ansible_executable` to match. +the connection variable :ref:`ansible_shell_type ` to select the plugin to use. +In this case, you will also want to update the :ref:`ansible_shell_executable ` to match. You can further control the settings for each plugin via other configuration options detailed in the plugin themselves (linked below). diff --git a/docs/docsite/rst/plugins/strategy.rst b/docs/docsite/rst/plugins/strategy.rst index 0ad820b6dc1..a3c2522af0c 100644 --- a/docs/docsite/rst/plugins/strategy.rst +++ b/docs/docsite/rst/plugins/strategy.rst @@ -34,7 +34,7 @@ or in the `ansible.cfg` file: [defaults] strategy=linear -You can also specify the strategy plugin in the play via the :ref:`strategy` keyword:: +You can also specify the strategy plugin in the play via the :ref:`strategy keyword ` in a play:: - hosts: all strategy: debug diff --git a/docs/docsite/rst/plugins/vars.rst b/docs/docsite/rst/plugins/vars.rst index bd3cda475dc..2e05dc2c233 100644 --- a/docs/docsite/rst/plugins/vars.rst +++ b/docs/docsite/rst/plugins/vars.rst @@ -8,7 +8,7 @@ Vars plugins inject additional variable data into Ansible runs that did not come Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4. -The :doc:`host_group_vars ` plugin shipped with Ansible enables reading variables from :ref:`host_vars` and :ref:`group_vars`. +The :ref:`host_group_vars ` plugin shipped with Ansible enables reading variables from :ref:`host_variables` and :ref:`group_variables`. .. _enable_vars: @@ -16,7 +16,7 @@ The :doc:`host_group_vars ` plugin shipped with Ansible en Enabling Vars Plugins +++++++++++++++++++++ -You can activate a custom vars plugins by either dropping it into a ``vars_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :ref:`ansible.cfg `. +You can activate a custom vars plugin by either dropping it into a ``vars_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :ref:`ansible.cfg `. .. _using_vars: diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst index 4be8417e651..6133818eaf8 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst @@ -111,7 +111,7 @@ In addition to the deprecation warnings, many new tests have been introduced tha when: result is successful -See :ref:`playbook_tests` for more information. +See :ref:`playbooks_tests` for more information. Additionally, a script was created to assist in the conversion for tests using filter syntax to proper jinja test syntax. This script has been used to convert all of the Ansible integration tests to the correct format. There are a few limitations documented, and all changes made by this script should be evaluated for correctness before executing the modified playbooks. The script can be found at `https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py `_. @@ -140,7 +140,7 @@ The following modules no longer exist: * :ref:`cl_license ` use :ref:`nclu ` instead * :ref:`cl_interface ` use :ref:`nclu ` instead * :ref:`cl_bond ` use :ref:`nclu ` instead -* :ref:`ec2_vpc ` use :ref:`ec2_vpc_net ` along with supporting modules :ref:`ec2_vpc_igw `, :ref:`ec2_vpc_route_table `, :ref:`ec2_vpc_subnet `, :ref:`ec2_vpc_dhcp_options `, :ref:`ec2_vpc_nat_gateway `, :ref:`ec2_vpc_nacl ` instead. +* :ref:`ec2_vpc ` use :ref:`ec2_vpc_net ` along with supporting modules :ref:`ec2_vpc_igw `, :ref:`ec2_vpc_route_table `, :ref:`ec2_vpc_subnet `, :ref:`ec2_vpc_dhcp_option `, :ref:`ec2_vpc_nat_gateway `, :ref:`ec2_vpc_nacl ` instead. * :ref:`ec2_ami_search ` use :ref:`ec2_ami_facts ` instead * :ref:`docker ` use :ref:`docker_container ` and :ref:`docker_image ` instead diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.6.rst b/docs/docsite/rst/porting_guides/porting_guide_2.6.rst index 2bc96fad434..f3713c2cf66 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.6.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.6.rst @@ -22,8 +22,7 @@ No notable changes. Deprecated ========== -* In the :ref:`nxos_igmp_interface ` module, `oif_prefix` and `oif_source` properties are deprecated. Use - `ois_ps` parameter with a dictionary of prefix and source to values instead. +* In the :ref:`nxos_igmp_interface module`, ``oif_prefix`` and ``oif_source`` properties are deprecated. Use ``ois_ps`` parameter with a dictionary of prefix and source to values instead. Modules ======= diff --git a/docs/docsite/rst/reference_appendices/common_return_values.rst b/docs/docsite/rst/reference_appendices/common_return_values.rst index 6aee8fc6569..9b9d6929bad 100644 --- a/docs/docsite/rst/reference_appendices/common_return_values.rst +++ b/docs/docsite/rst/reference_appendices/common_return_values.rst @@ -1,3 +1,5 @@ +.. _common_return_values: + Return Values ------------- @@ -11,8 +13,6 @@ This document covers return values common to all modules. .. note:: Some of these keys might be set by Ansible itself once it processes the module's return information. -.. _common_return_values: - Common ^^^^^^ diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 25901935b96..7f74aa99642 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -19,6 +19,7 @@ Setting environment variables can be done with the `environment` keyword. It can .. note:: starting in 2.0.1 the setup task from gather_facts also inherits the environment directive from the play, you might need to use the `|default` filter to avoid errors if setting this at play level. +.. _faq_setting_users_and_ports: How do I handle different machines needing different user accounts or ports to log in with? +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -185,12 +186,12 @@ By default, Solaris 10 and earlier run a non-POSIX shell which does not correctl tmp directory Ansible uses ( :file:`~/.ansible/tmp`). If you see module failures on Solaris machines, this is likely the problem. There are several workarounds: -* You can set :ref:`remote_tmp` to a path that will expand correctly with the Solaris shell. For +* You can set ``remote_tmp`` to a path that will expand correctly with the shell you are using (see the plugin documentation for :ref:`C shell`, :ref:`fish shell`, and :ref:`Powershell`). For example, in the ansible config file you can set:: remote_tmp=$HOME/.ansible/tmp - In Ansible 2.5 and later, you can also set it per-host like this:: + In Ansible 2.5 and later, you can also set it per-host in inventory like this:: solaris1 ansible_remote_tmp=$HOME/.ansible/tmp diff --git a/docs/docsite/rst/reference_appendices/python_3_support.rst b/docs/docsite/rst/reference_appendices/python_3_support.rst index ff43e904704..3eca64a5402 100644 --- a/docs/docsite/rst/reference_appendices/python_3_support.rst +++ b/docs/docsite/rst/reference_appendices/python_3_support.rst @@ -88,5 +88,5 @@ If you find a bug running under Python 3 you can submit a bug report on `Ansible that the right people look at it. If you would like to fix the code and submit a pull request on github, you can -refer to :ref:`developing_python3` for information on how we fix +refer to :ref:`developing_python_3` for information on how we fix common Python3 compatibility issues in the Ansible codebase. diff --git a/docs/docsite/rst/user_guide/intro_inventory.rst b/docs/docsite/rst/user_guide/intro_inventory.rst index 1bc792ddc36..ccce561fb10 100644 --- a/docs/docsite/rst/user_guide/intro_inventory.rst +++ b/docs/docsite/rst/user_guide/intro_inventory.rst @@ -388,9 +388,11 @@ ansible_become_flags Remote host environment parameters: +.. _ansible_shell_type: + ansible_shell_type The shell type of the target system. You should not use this setting unless you have set the - :ref:`ansible_shell_executable` to a non-Bourne (sh) compatible shell. By default commands are + :ref:`ansible_shell_executable` to a non-Bourne (sh) compatible shell. By default commands are formatted using ``sh``-style syntax. Setting this to ``csh`` or ``fish`` will cause commands executed on target systems to follow those shell's syntax instead. @@ -404,7 +406,7 @@ ansible_python_interpreter be named something like :program:`python2.6`. ansible_*_interpreter - Works for anything such as ruby or perl and works just like :ref:`ansible_python_interpreter`. + Works for anything such as ruby or perl and works just like :ref:`ansible_python_interpreter`. This replaces shebang of modules which will run on that host. .. versionadded:: 2.1 diff --git a/docs/docsite/rst/user_guide/modules_support.rst b/docs/docsite/rst/user_guide/modules_support.rst index 161986b753b..c64fdebf5db 100644 --- a/docs/docsite/rst/user_guide/modules_support.rst +++ b/docs/docsite/rst/user_guide/modules_support.rst @@ -10,13 +10,13 @@ To help identify maintainers and understand how the included modules are officia Core ```` -:ref:`core_supported`. These are maintained by the Ansible Engineering Team. +:ref:`Core Maintained` modules are maintained by the Ansible Engineering Team. These modules are integral to the basic foundations of the Ansible distribution. Network ``````` -:ref:`network_supported`. These are maintained by the Ansible Network Team. Please note there are additional networking modules that are categorized as Certified or Community not maintained by Ansible. +:ref:`Network Maintained` modules are are maintained by the Ansible Network Team. Please note there are additional networking modules that are categorized as Certified or Community not maintained by Ansible. Certified @@ -27,7 +27,7 @@ Certified modules are part of a future planned program currently in development. Community ````````` -:ref:`community_supported`. These are submitted and maintained by the Ansible community. These modules are not maintained by Ansible, and are included as a convenience. +:ref:`Community Maintained` modules are submitted and maintained by the Ansible community. These modules are not maintained by Ansible, and are included as a convenience. Issue Reporting ``````````````` diff --git a/docs/docsite/rst/user_guide/playbooks_roles.rst b/docs/docsite/rst/user_guide/playbooks_roles.rst index 94f09cd7cf5..6a84763a0a1 100644 --- a/docs/docsite/rst/user_guide/playbooks_roles.rst +++ b/docs/docsite/rst/user_guide/playbooks_roles.rst @@ -1,3 +1,5 @@ +:orphan: + Playbook Roles and Include Statements ===================================== diff --git a/docs/docsite/rst/user_guide/playbooks_strategies.rst b/docs/docsite/rst/user_guide/playbooks_strategies.rst index 23933a6e3c3..c7c5b0a796b 100644 --- a/docs/docsite/rst/user_guide/playbooks_strategies.rst +++ b/docs/docsite/rst/user_guide/playbooks_strategies.rst @@ -1,3 +1,5 @@ +.. _playbooks_strategies: + Strategies =========== diff --git a/docs/templates/modules_by_category.rst.j2 b/docs/templates/modules_by_category.rst.j2 index 4034ec36a19..0b8f4d0d285 100644 --- a/docs/templates/modules_by_category.rst.j2 +++ b/docs/templates/modules_by_category.rst.j2 @@ -1,3 +1,8 @@ +.. _modules_by_category: + +{# avoids rST "isn't included in any toctree" errors for module index docs #} +:orphan: + Module Index ============ diff --git a/docs/templates/modules_by_support.rst.j2 b/docs/templates/modules_by_support.rst.j2 index a8c8fa78fc8..368a2f0b0d3 100644 --- a/docs/templates/modules_by_support.rst.j2 +++ b/docs/templates/modules_by_support.rst.j2 @@ -1,5 +1,8 @@ .. _@{ slug }@: +{# avoids rST "isn't included in any toctree" errors for module index docs #} +:orphan: + Modules Maintained by the @{ maintainers }@ ``````````````````````````@{ '`' * maintainers | length }@