From 893807bfc91bce8e3d691e40528e6f8f40353133 Mon Sep 17 00:00:00 2001
From: scottb <dharmabumstead@users.noreply.github.com>
Date: Tue, 17 Apr 2018 18:45:07 -0700
Subject: [PATCH] [WIP] disambiguating autogenerated module docs attempted fix
 of #38439. (#38890)

Disambiguates autogenerated module docs - fixes #38439.

(cherry picked from commit c97e5088061a8b4c7420da1b9b5e30ad2ef82467)
---
 .../intro_configuration.rst                   |  5 ++--
 docs/docsite/rst/plugins/callback.rst         | 30 ++++++++++---------
 docs/docsite/rst/user_guide/intro_adhoc.rst   |  9 +++---
 docs/templates/config.rst.j2                  |  2 ++
 .../templates/list_of_CATEGORY_modules.rst.j2 |  4 +--
 docs/templates/modules_by_support.rst.j2      |  2 +-
 docs/templates/plugin.rst.j2                  |  2 +-
 7 files changed, 30 insertions(+), 24 deletions(-)

diff --git a/docs/docsite/rst/installation_guide/intro_configuration.rst b/docs/docsite/rst/installation_guide/intro_configuration.rst
index 530ae8b4a0e..e68b0d62507 100644
--- a/docs/docsite/rst/installation_guide/intro_configuration.rst
+++ b/docs/docsite/rst/installation_guide/intro_configuration.rst
@@ -33,7 +33,7 @@ An `example file is available on Github <https://raw.github.com/ansible/ansible/
 
 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:`config`.
+For in-depth details, see :ref:`ansible_configuration_settings`.
 
 
 Environmental configuration
@@ -42,7 +42,8 @@ Environmental configuration
 Ansible also allows configuration of settings using environment variables.
 If these environment variables are set, they will override any setting loaded from the configuration file.
 
-You can get a full listing of available environment variables from :doc:`_config`.
+You can get a full listing of available environment variables from :ref:`ansible_configuration_settings`.
+
 
 .. _command_line_configuration:
 
diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst
index a54ac6c1c3f..08fe8d8b363 100644
--- a/docs/docsite/rst/plugins/callback.rst
+++ b/docs/docsite/rst/plugins/callback.rst
@@ -50,13 +50,13 @@ or for my custom callback:
 
   stdout_callback = mycallback
 
-This only affects :doc:`../ansible-playbook` by default.
+This only affects :ref:`ansible-playbook` by default.
 
 Managing AdHoc
 ``````````````
 
-The :doc:`ansible <../ansible>` AdHoc command specifically uses a different callback plugin for stdout,
-so there is an extra setting in :doc:`ansible.cfg <../config>` you need to add to use the stdout callback defined above:
+The :ref:`ansible` ad hoc command specifically uses a different callback plugin for stdout,
+so there is an extra setting in :ref:`ansible_configuration_settings` you need to add to use the stdout callback defined above:
 
 .. code-block:: ini
 
@@ -87,19 +87,21 @@ Use ``ansible-doc -t callback <plugin name>`` to see specific documents and exam
 
 .. seealso::
 
-   :doc:`../playbooks`
-       An introduction to playbooks
+   :doc:`action`
+       Ansible Action plugins
+   :doc:`cache`
+       Ansible cache plugins
+   :doc:`connection`
+       Ansible connection plugins
    :doc:`inventory`
        Ansible inventory plugins
-   :doc:`../playbooks_filters`
-       Jinja2 filter plugins
-   :doc:`../playbooks_tests`
-       Jinja2 test plugins
-   :doc:`../playbooks_lookups`
-       Jinja2 lookup plugins
+   :doc:`shell`
+       Ansible Shell plugins
+   :doc:`strategy`
+       Ansible Strategy plugins
    :doc:`vars`
-       Ansible vars plugins
-   `User Mailing List <http://groups.google.com/group/ansible-devel>`_
+       Ansible Vars plugins
+   `User Mailing List <https://groups.google.com/forum/#!forum/ansible-devel>`_
        Have a question?  Stop by the google group!
-   `irc.freenode.net <http://irc.freenode.net>`_
+   `webchat.freenode.net <https://webchat.freenode.net>`_
        #ansible IRC chat channel
diff --git a/docs/docsite/rst/user_guide/intro_adhoc.rst b/docs/docsite/rst/user_guide/intro_adhoc.rst
index 74991ddeedb..0dd9e9fb6ef 100644
--- a/docs/docsite/rst/user_guide/intro_adhoc.rst
+++ b/docs/docsite/rst/user_guide/intro_adhoc.rst
@@ -94,11 +94,12 @@ specify that all of the time.  We'll use ``-m`` in later examples to
 run some other :doc:`modules`.
 
 .. note::
-   The :ref:`command` module does not support extended shell syntax like piping and redirects (although
-   shell variables will always work). If your command requires shell-specific syntax, use the `shell` module
-   instead. Read more about the differences on the :ref:`working_with_modules` page.
+   The :ref:`command module <module_command>` does not support extended shell syntax like piping and
+   redirects (although shell variables will always work). If your command requires shell-specific
+   syntax, use the `shell` module instead. Read more about the differences on the
+   :ref:`working_with_modules` page.
 
-Using the :ref:`shell` module looks like this::
+Using the :ref:`shell module <module_shell>` looks like this::
 
     $ ansible raleigh -m shell -a 'echo $TERM'
 
diff --git a/docs/templates/config.rst.j2 b/docs/templates/config.rst.j2
index 0ff9e0f5e47..cf0cb91ef4d 100644
--- a/docs/templates/config.rst.j2
+++ b/docs/templates/config.rst.j2
@@ -1,3 +1,5 @@
+.. _ansible_configuration_settings:
+
 {% set name = 'Ansible Configuration Settings' -%}
 {% set name_slug = 'config' -%}
 
diff --git a/docs/templates/list_of_CATEGORY_modules.rst.j2 b/docs/templates/list_of_CATEGORY_modules.rst.j2
index 05ab5e2f5e2..808451b0b70 100644
--- a/docs/templates/list_of_CATEGORY_modules.rst.j2
+++ b/docs/templates/list_of_CATEGORY_modules.rst.j2
@@ -11,7 +11,7 @@
 {% if category['_modules'] %}
 
 {% for module in category['_modules'] | sort %}
-  * :ref:`@{ module }@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} 
+  * :ref:`@{ module }@_@{ plugin_type }@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} 
 {% endfor %}
 {% endif %}
 
@@ -25,7 +25,7 @@
 
 
 {% for module in info['_modules'] | sort %}
-  * :ref:`@{ module }@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} 
+  * :ref:`@{ module }@_@{ plugin_type }@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} 
 {% endfor %}
 
 {% endfor %}
diff --git a/docs/templates/modules_by_support.rst.j2 b/docs/templates/modules_by_support.rst.j2
index 1446e1592bf..a8c8fa78fc8 100644
--- a/docs/templates/modules_by_support.rst.j2
+++ b/docs/templates/modules_by_support.rst.j2
@@ -4,7 +4,7 @@ Modules Maintained by the @{ maintainers }@
 ``````````````````````````@{ '`' * maintainers | length }@
 
 {% for module in modules | sort %}
-  * :ref:`@{ module }@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} 
+  * :ref:`@{ module }@_@{plugin_type}@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} 
 {% endfor %}
 
 .. note::
diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2
index 706130efc00..e9f075ac145 100644
--- a/docs/templates/plugin.rst.j2
+++ b/docs/templates/plugin.rst.j2
@@ -1,6 +1,6 @@
 :source: @{ source }@
 
-.. _@{ module }@:
+.. _@{ module }@_@{ plugin_type }@:
 {% for alias in aliases %}
 .. _@{ alias }@:
 {% endfor %}