Reduce warnings (#39254) (#39323)

* fixes from 4b52a54e18
* leaves out the stub 2.6 porting guide

docs/docsite/rst/community/community.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Community Information & Contributing
 ````````````````````````````````````
 

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 <ansible-metadata-block>` for more information.
+Read the complete :ref:`module metadata specification <ansible_metadata_block>` 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 <ansible-metadata-block>`
 * 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 <ansible-metadata-block>`
   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
+* facts modules must return facts in the ansible_facts field of the :ref:`result
-  dictionary. :ref:`module_provided_facts`
+  dictionary<common_return_values>`.
 * 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

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.

docs/docsite/rst/dev_guide/testing_running_locally.rst

@@ -1,3 +1,5 @@
+.. _testing_running_locally:
+
 ***************
 Testing Ansible
 ***************

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

docs/docsite/rst/dev_guide/testing_units_modules.rst

@@ -1,3 +1,5 @@
+.. _testing_units_modules:
+
 ****************************
 Unit Testing Ansible Modules
 ****************************

docs/docsite/rst/installation_guide/intro_configuration.rst

@@ -31,7 +31,7 @@ default settings in Ansible.
 
 An `example file is available on Github <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_.
 
-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<ansible_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`.
 

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<yum_module>` or :ref:`dnf module<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<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<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<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
 

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 <playbooks_vault>`.

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.  
+By default, Ansible ships with several plugins. The most commonly used are the :ref:`paramiko SSH<paramiko_ssh_connection>`, native ssh (just called :ref:`ssh<ssh_connection>`), and :ref:`local<local_connection>` 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<intro_getting_started>` section.  
 
+The basics of these connection types are covered in the :ref:`getting started<intro_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<ansible_configuration_settings>`, in the command line (``-c``, ``--connection``), as a :ref:`keyword<playbooks_keywords>`)
+The transport can be changed via :ref:`configuration<ansible_configuration_settings>`, at the command line (``-c``, ``--connection``), as a :ref:`keyword <playbooks_keywords>` in your play, or by setting a :ref:`variable<behavioral_parameters>`, most often in your inventory.
-in your play, or by setting a :ref:`variable<behavioral_parameters>`, most often in your inventory.
 For example, for Windows machines you might want to use the :doc:`winrm<connection/winrm>` plugin.
 
-Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory hostname<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<inventory_hostnames_lookup>` 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<ansible_host>`
+:ref:`ansible_host<magic_variables_and_hostvars>`
-    The name of the host to connect to, if different from the :ref:`inventory hostname<inventory_hostname>`.
+    The name of the host to connect to, if different from the :ref:`inventory <intro_inventory>` hostname.
-:ref:`ansible_port<ansible_port>`
+:ref:`ansible_port<faq_setting_users_and_ports>`
-    The ssh port number, for :doc:`ssh <connection/ssh>` and :doc:`paramiko <connection/paramiko>` it defaults to 22.
+    The ssh port number, for :ref:`ssh <ssh_connection>` and :ref:`paramiko_ssh <paramiko_ssh_connection>` it defaults to 22.
-:ref:`ansible_user<ansible_user>`
+:ref:`ansible_user<faq_setting_users_and_ports>`
     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<ansible_ssh_host>` for the :doc:`ssh <connection/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 <ssh_connection>` plugin.
 
 .. _connection_plugin_list:
 

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.
+the connection variable :ref:`ansible_shell_type <ansible_shell_type>` to select the plugin to use.
-In this case, you will also want to update the :ref:`ansible_executable` to match.
+In this case, you will also want to update the :ref:`ansible_shell_executable <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).

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 <playbooks_keywords>` in a play::
 
   - hosts: all
     strategy: debug

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 <vars/host_group_vars>` plugin shipped with Ansible enables reading variables from :ref:`host_vars` and :ref:`group_vars`.
+The :ref:`host_group_vars <host_group_vars_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 <vars/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 <ansible_configuration_settings>`.
+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 <ansible_configuration_settings>`.
 
 
 .. _using_vars:

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 <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 <cl_license_module>` use :ref:`nclu <nclu_module>` instead
 * :ref:`cl_interface <cl_interface_module>` use :ref:`nclu <nclu_module>` instead
 * :ref:`cl_bond <cl_bond_module>` use :ref:`nclu <nclu_module>` instead
-* :ref:`ec2_vpc <ec2_vpc_module>` use :ref:`ec2_vpc_net <ec2_vpc_net_module>` along with supporting modules :ref:`ec2_vpc_igw <ec2_vpc_igw_module>`, :ref:`ec2_vpc_route_table <ec2_vpc_route_table_module>`, :ref:`ec2_vpc_subnet <ec2_vpc_subnet_module>`, :ref:`ec2_vpc_dhcp_options <ec2_vpc_dhcp_options_module>`, :ref:`ec2_vpc_nat_gateway <ec2_vpc_nat_gateway_module>`, :ref:`ec2_vpc_nacl <ec2_vpc_nacl_module>` instead.
+* :ref:`ec2_vpc <ec2_vpc_module>` use :ref:`ec2_vpc_net <ec2_vpc_net_module>` along with supporting modules :ref:`ec2_vpc_igw <ec2_vpc_igw_module>`, :ref:`ec2_vpc_route_table <ec2_vpc_route_table_module>`, :ref:`ec2_vpc_subnet <ec2_vpc_subnet_module>`, :ref:`ec2_vpc_dhcp_option <ec2_vpc_dhcp_option_module>`, :ref:`ec2_vpc_nat_gateway <ec2_vpc_nat_gateway_module>`, :ref:`ec2_vpc_nacl <ec2_vpc_nacl_module>` instead.
 * :ref:`ec2_ami_search <ec2_ami_search_module>` use :ref:`ec2_ami_facts <ec2_ami_facts_module>` instead
 * :ref:`docker <docker_module>` use :ref:`docker_container <docker_container_module>` and :ref:`docker_image <docker_image_module>` instead
 

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

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<csh_shell>`, :ref:`fish shell<fish_shell>`, and :ref:`Powershell<powershell_shell>`).  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
 

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.

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<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<ansible_python_interpreter>`.
     This replaces shebang of modules which will run on that host.
 
 .. versionadded:: 2.1

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<core_supported>` 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<network_supported>` 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<community_supported>` modules are submitted and maintained by the Ansible community.  These modules are not maintained by Ansible, and are included as a convenience.
 
 Issue Reporting
 ```````````````

docs/docsite/rst/user_guide/playbooks_roles.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Playbook Roles and Include Statements
 =====================================
 

docs/docsite/rst/user_guide/playbooks_strategies.rst

@@ -1,3 +1,5 @@
+.. _playbooks_strategies:
+
 Strategies
 ===========
 

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

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 }@