Reduce warnings (#39254)

* removes FAQ links; no entries exist for linked config settings

* fixes various anchors and links

* addresses abadger comments, thanks

* marks orphan pages, avoids TOC errors

* adds links for remote_tmp setting to FAQ

24 files changed, 65 insertions, 47 deletions

diff --git a/docs/docsite/rst/community/community.rst b/docs/docsite/rst/community/community.rst
index 5a62d20a76..5dadb7bc9e 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 e28f05fc52..9538066e68 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 <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
-  dictionary. :ref:`module_provided_facts`
+* facts modules must return facts in the ansible_facts field of the :ref:`result
+  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
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 cd50b98d97..420c1a3d4b 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 2f5ac0ee2a..4387709775 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 0290514be5..a7df079d98 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 490a271f0e..91bc14ddf0 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 e68b0d6250..37977b0373 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 <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`.
 
diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst
index 76c0d55173..cf8f401c0a 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<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
 
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 27424f5777..e7d4bdef56 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 <playbooks_vault>`.
diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst
index cdba361764..468ab4e37b 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<intro_getting_started>` section.  
+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.
 
 .. _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>`)
-in your play, or by setting a :ref:`variable<behavioral_parameters>`, most often in your inventory.
+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.
 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>`
-    The name of the host to connect to, if different from the :ref:`inventory hostname<inventory_hostname>`.
-:ref:`ansible_port<ansible_port>`
-    The ssh port number, for :doc:`ssh <connection/ssh>` and :doc:`paramiko_ssh <connection/paramiko_ssh>` it defaults to 22.
-:ref:`ansible_user<ansible_user>`
+:ref:`ansible_host<magic_variables_and_hostvars>`
+    The name of the host to connect to, if different from the :ref:`inventory <intro_inventory>` hostname.
+:ref:`ansible_port<faq_setting_users_and_ports>`
+    The ssh port number, for :ref:`ssh <ssh_connection>` and :ref:`paramiko_ssh <paramiko_ssh_connection>` it defaults to 22.
+: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:
 
diff --git a/docs/docsite/rst/plugins/shell.rst b/docs/docsite/rst/plugins/shell.rst
index 714730393f..708bfe79d0 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 <ansible_shell_type>` to select the plugin to use.
+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).
diff --git a/docs/docsite/rst/plugins/strategy.rst b/docs/docsite/rst/plugins/strategy.rst
index 0ad820b6dc..a3c2522af0 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 <playbooks_keywords>` in a play::
 
   - hosts: all
     strategy: debug
diff --git a/docs/docsite/rst/plugins/vars.rst b/docs/docsite/rst/plugins/vars.rst
index bd3cda475d..2e05dc2c23 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 <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:
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 4be8417e65..6133818eaf 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 <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
 
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 2bc96fad43..f3713c2cf6 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 <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<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 6aee8fc656..9b9d6929ba 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 25901935b9..7f74aa9964 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<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
 
diff --git a/docs/docsite/rst/reference_appendices/python_3_support.rst b/docs/docsite/rst/reference_appendices/python_3_support.rst
index ff43e90470..3eca64a540 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 1bc792ddc3..ccce561fb1 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<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
diff --git a/docs/docsite/rst/user_guide/modules_support.rst b/docs/docsite/rst/user_guide/modules_support.rst
index 161986b753..c64fdebf5d 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<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
 ```````````````
diff --git a/docs/docsite/rst/user_guide/playbooks_roles.rst b/docs/docsite/rst/user_guide/playbooks_roles.rst
index 94f09cd7cf..6a84763a0a 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 23933a6e3c..c7c5b0a796 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 4034ec36a1..0b8f4d0d28 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 a8c8fa78fc..368a2f0b0d 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 }@