Misc docsite fixes (#30290)

* Fix refs for local_facts and various cli :option:
* Fix dev_guide/testing_pep8 refs
* remove ref to non-existing 'developing_test_pr'
* Fix ref to ansible-vault encrypt_string
* Removed hard-to-localize colloquialism.
* Rename '_ansible-pull' in playbooks_intro.

It was conflicting with rst/ansible-pull.rst. Nothing
seems to reference it.

* Add explicit targets for and update refs

Replace some ':doc:' use with ':ref:'.

Replace some :ref: to section names with explicit targets
(:doc:`Dynamic vs. Static` -> :ref:`dynamic_vs_static` etc)

* The 'YAML+Jinja' syntax lex fails here, so just use yaml

Since the yaml+jinja highlight fails, code wasnt highlighted
at all, but 'yaml' works more or less.

* just use no lexer for the < python2.6 examples

py3 will fail highlighting them, and 'python2' throws
a lexer warning, and nothing actually highlights it, so
just disable.

(cherry picked from commit 9cc63326b1441a47d7782cf6fbdf4cc9a6e1d0fb)

13 files changed, 29 insertions, 50 deletions

diff --git a/docs/docsite/rst/community.rst b/docs/docsite/rst/community.rst
index 6b4f30f773..d3399bdd92 100644
--- a/docs/docsite/rst/community.rst
+++ b/docs/docsite/rst/community.rst
@@ -179,7 +179,7 @@ please observe the following guidelines:
 - Use a 4-space indent, not  tabs.
 - We do not enforce 80 column lines; up to 160 columns are acceptable.
 - We do not accept 'style only' pull requests unless the code is nearly unreadable.
-- We are "PEP8ish", but not strictly compliant, see :doc:`testing_pep8` for more information.
+- We are not strictly compliant with PEP8. See :doc:`dev_guide/testing_pep8` for more information.
 
 You can also contribute by testing and revising other requests, especially if it is one you are interested
 in using. Please keep your comments clear and to the point, courteous and constructive, tickets are not a
diff --git a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst
index 7a0300da8c..5ea904010c 100644
--- a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst
+++ b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst
@@ -26,7 +26,7 @@ Although it's tempting to get straight into coding, there are a few things to be
 * Shared code can be placed into ``lib/ansible/module_utils/``
 * Shared documentation (for example describing common arguments) can be placed in ``lib/ansible/utils/module_docs_fragments/``.
 * With great power comes great responsibility: Ansible module maintainers have a duty to help keep modules up to date. As with all successful community projects, module maintainers should keep a watchful eye for reported issues and contributions.
-* Although not required, unit and/or integration tests are strongly recommended. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :doc:`testing` and the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
+* Although not required, unit and/or integration tests are strongly recommended. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :doc:`dev_guide/testing` and the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
   * Starting with Ansible 2.4 all :doc:`../list_of_network_modules` MUST have unit tests.
 
 
diff --git a/docs/docsite/rst/dev_guide/developing_python3.rst b/docs/docsite/rst/dev_guide/developing_python3.rst
index 17f3d562b9..86913e42cd 100644
--- a/docs/docsite/rst/dev_guide/developing_python3.rst
+++ b/docs/docsite/rst/dev_guide/developing_python3.rst
@@ -295,7 +295,7 @@ new exception-catching syntax which uses the ``as`` keyword:
 Do **not** use the following syntax as it will fail on every version of Python-3:
 
 .. This code block won't highlight because python2 isn't recognized. This is necessary to pass tests under python 3.
-.. code-block:: python2
+.. code-block:: none
 
     try:
         a = 2/0
diff --git a/docs/docsite/rst/dev_guide/index.rst b/docs/docsite/rst/dev_guide/index.rst
index f61ddd99ec..cb75dfb70a 100644
--- a/docs/docsite/rst/dev_guide/index.rst
+++ b/docs/docsite/rst/dev_guide/index.rst
@@ -30,7 +30,6 @@ To get started, select one of the following topics.
    developing_core
    developing_python3
    developing_api
-   developing_test_pr
    developing_rebasing
    testing
    repomerge
diff --git a/docs/docsite/rst/intro_configuration.rst b/docs/docsite/rst/intro_configuration.rst
index 1cf8217c2d..73572a5abb 100644
--- a/docs/docsite/rst/intro_configuration.rst
+++ b/docs/docsite/rst/intro_configuration.rst
@@ -443,7 +443,7 @@ value is a TTL in seconds::
 fact_path
 =========
 
-This option allows you to globally configure a custom path for :ref:`_local_facts`:: for the implied `setup` task when using implied fact gathering.
+This option allows you to globally configure a custom path for :ref:`local_facts` for the implied `setup` task when using implied fact gathering.
 
   fact_path = /home/centos/ansible_facts.d
 
@@ -657,15 +657,15 @@ merge_multiple_cli_tags
 
 .. versionadded:: 2.3
 
-This allows changing how multiple :option:`--tags` and :option:`--skip-tags`
-arguments are handled on the command line.  Specifying :option:`--tags` more
-than once merges all of the :option:`--tags` options together.  If you want
-the pre-2.4.x behaviour where only the last value of :option:`--tags` is used,
-then set this to False.  The same holds true for :option:`--skip-tags`.
+This allows changing how multiple :option:`--tags <ansible-playbook --tags>` and :option:`--skip-tags <ansible-playbook --skip-tags>`
+arguments are handled on the command line.  Specifying :option:`--tags <ansible-playbook --tags>` more
+than once merges all of the :option:`--tags <ansible-playbook --tags>` options together.  If you want
+the pre-2.4.x behaviour where only the last value of :option:`--tags <ansible-playbook --tags>` is used,
+then set this to False.  The same holds true for :option:`--skip-tags <ansible-playbook --skip-tags>`.
 
 .. note:: The default value for this in 2.3 is False.  In 2.4, the
     default value is True.  After 2.8, the option will be removed.
-    Multiple :option:`--tags` and multiple :option:`--skip-tags` will always
+    Multiple :option:`--tags <ansible-playbook --tags>` and multiple :option:`--skip-tags <ansible-playbook --skip-tags>` will always
     be merged together.
 
 .. _module_lang:
@@ -814,26 +814,6 @@ always default to the current user if this is not defined::
     remote_user = root
 
 
-.. _restrict_facts_namespace:
-
-restrict_facts_namespace
-========================
-
-.. versionadded:: 2.4
-
-This allows restricting facts in their own namespace (under ansible_facts) instead of pushing them into the main.
-False by default. Can also be set via the environment variable :envvar:`ANSIBLE_RESTRICT_FACTS`. Using `ansible_system` as an example:
-
-When False::
-
-    - debug: var=ansible_system
-
-
-When True::
-
-    - debug: var=ansible_facts.ansible_system
-
-
 .. _retry_files_enabled:
 
 retry_files_enabled
@@ -1025,7 +1005,7 @@ As of 1.7 this file can also be a script. If you are using a script instead of a
 Privilege Escalation Settings
 -----------------------------
 
-Ansible can use existing privilege escalation systems to allow a user to execute tasks as another. As of 1.9 ‘become’ supersedes the old sudo/su, while still being backwards compatible.  Settings live under the [privilege_escalation] header.
+Ansible can use existing privilege escalation systems to allow a user to execute tasks as another. As of 1.9 'become' supersedes the old sudo/su, while still being backwards compatible.  Settings live under the [privilege_escalation] header.
 
 .. _become:
 
diff --git a/docs/docsite/rst/playbooks_intro.rst b/docs/docsite/rst/playbooks_intro.rst
index ee87316b06..81e4822b43 100644
--- a/docs/docsite/rst/playbooks_intro.rst
+++ b/docs/docsite/rst/playbooks_intro.rst
@@ -458,7 +458,7 @@ Let's run a playbook using a parallelism level of 10::
 
     ansible-playbook playbook.yml -f 10
 
-.. _ansible-pull:
+.. _playbook_ansible-pull:
 
 Ansible-Pull
 ````````````
diff --git a/docs/docsite/rst/playbooks_lookups.rst b/docs/docsite/rst/playbooks_lookups.rst
index 314cadb14f..0e57fb927f 100644
--- a/docs/docsite/rst/playbooks_lookups.rst
+++ b/docs/docsite/rst/playbooks_lookups.rst
@@ -458,7 +458,7 @@ Please check https://api.mongodb.org/python/current/api/pymongo/collection.html?
 
 Since there are too many parameters for this lookup method, below is a sample playbook which shows its usage and a nice way to feed the parameters:
 
-.. code-block:: YAML+Jinja
+.. code-block:: yaml
 
     ---
     - hosts: all
diff --git a/docs/docsite/rst/playbooks_prompts.rst b/docs/docsite/rst/playbooks_prompts.rst
index 6b5b2ea0fb..3070342eb1 100644
--- a/docs/docsite/rst/playbooks_prompts.rst
+++ b/docs/docsite/rst/playbooks_prompts.rst
@@ -27,8 +27,9 @@ Here is a most basic example::
         - name: "favcolor"
           prompt: "what is your favorite color?"
 
+
 .. note::
-   Prompts for individual ``vars_prompt`` variables will be skipped for any variable that is already defined through the command line ``--extra-vars`` option, or when running from a non-interactive session (such as cron or Ansible Tower). See :ref:`_passing_variables_on_the_command_line` in the /Variables/ chapter.
+    Prompts for individual ``vars_prompt`` variables will be skipped for any variable that is already defined through the command line ``--extra-vars`` option, or when running from a non-interactive session (such as cron or Ansible Tower). See :ref:`passing_variables_on_the_command_line` in the /Variables/ chapter.
 
 If you have a variable that changes infrequently, it might make sense to
 provide a default value that can be overridden.  This can be accomplished using
diff --git a/docs/docsite/rst/playbooks_reuse.rst b/docs/docsite/rst/playbooks_reuse.rst
index ade1ab11e0..8fa12b2bf5 100644
--- a/docs/docsite/rst/playbooks_reuse.rst
+++ b/docs/docsite/rst/playbooks_reuse.rst
@@ -13,6 +13,8 @@ Includes and imports (added in 2.4) allow users to break up large playbooks into
 
 Roles allow more than just tasks to be packaged together and can include variables, handlers, or even modules and other plugins. Unlike includes and imports, roles can also be uploaded and shared via Ansible Galaxy.
 
+.. _dynamic_vs_static:
+
 Dynamic vs. Static
 ``````````````````
 
diff --git a/docs/docsite/rst/playbooks_reuse_includes.rst b/docs/docsite/rst/playbooks_reuse_includes.rst
index d4fca33802..df6cf7b28c 100644
--- a/docs/docsite/rst/playbooks_reuse_includes.rst
+++ b/docs/docsite/rst/playbooks_reuse_includes.rst
@@ -69,7 +69,7 @@ Variables can also be passed to include files using an alternative syntax, which
         - "{{ lookup('file', 'keys/one.pub') }}"
         - "{{ lookup('file', 'keys/two.pub') }}"
 
-Using either syntax, variables passed in can then be used in the included files. These variables will only be available to tasks within the included file. See :doc:`variable_precedence` for more details on variable inheritance and precedence.
+Using either syntax, variables passed in can then be used in the included files. These variables will only be available to tasks within the included file. See :ref:`variable_precedence` for more details on variable inheritance and precedence.
 
 Task include statements can be used at arbitrary depth.
 
diff --git a/docs/docsite/rst/playbooks_reuse_roles.rst b/docs/docsite/rst/playbooks_reuse_roles.rst
index f019376319..5df2ad497e 100644
--- a/docs/docsite/rst/playbooks_reuse_roles.rst
+++ b/docs/docsite/rst/playbooks_reuse_roles.rst
@@ -33,8 +33,8 @@ Roles expect files to be in certain directory names. Roles must include at least
 
 - ``tasks`` - contains the main list of tasks to be executed by the role.
 - ``handlers`` - contains handlers, which may be used by this role or even anywhere outside this role.
-- ``defaults`` - default variables for the role (see :doc:`Variables` for more information).
-- ``vars`` - other variables for the role (see :doc:`Variables` for more information).
+- ``defaults`` - default variables for the role (see :doc:`playbooks_variables` for more information).
+- ``vars`` - other variables for the role (see :doc:`playbooks_variables` for more information).
 - ``files`` - contains files which can be deployed via this role.
 - ``templates`` - contains templates which can be deployed via this role.
 - ``meta`` - defines some meta data for this role. See below for more details.
@@ -58,7 +58,7 @@ Other YAML files may be included in certain directories. For example, it is comm
         name: "apache2"
         state: present
 
-Roles may also include modules and other plugin types. For more information, please refer to the :doc:`Embedding Modules and Plugins In Roles` section below.
+Roles may also include modules and other plugin types. For more information, please refer to the :ref:`embedding_modules_and_plugins_in_roles` section below.
 
 Using Roles
 ```````````
@@ -114,9 +114,9 @@ As of Ansible 2.4, you can now use roles inline with any other tasks using ``imp
 When roles are defined in the classic manner, they are treated as static imports and processed during playbook parsing.
 
 .. note::
-    The ``include_role`` option was introduced in Ansible 2.3. The usage has changed slightly as of Ansible 2.4 to match the include (dynamic) vs. import (static) usage. See :doc:`Dynamic vs. Static` for more details.
+    The ``include_role`` option was introduced in Ansible 2.3. The usage has changed slightly as of Ansible 2.4 to match the include (dynamic) vs. import (static) usage. See :ref:`dynamic_vs_static` for more details.
 
-The name used for the role can be a simple name (see :doc:`Role Search Path` below), or it can be a fully qualified path::
+The name used for the role can be a simple name (see :ref:`role_search_path` below), or it can be a fully qualified path::
 
     ---
 
@@ -291,6 +291,8 @@ Note that we did not have to use ``allow_duplicates: true`` for ``wheel``, becau
 .. note::
    Variable inheritance and scope are detailed in the :doc:`playbooks_variables`.
 
+.. _embedding_modules_and_plugins_in_roles:
+
 Embedding Modules and Plugins In Roles
 ``````````````````````````````````````
 
@@ -333,6 +335,8 @@ The same mechanism can be used to embed and distribute plugins in a role, using
 
 They can then be used in a template or a jinja template in any role called after 'my_custom_filter'
 
+.. _role_search_path:
+
 Role Search Path
 ````````````````
 
diff --git a/docs/docsite/rst/playbooks_vault.rst b/docs/docsite/rst/playbooks_vault.rst
index 6d9afd4b84..1e70dc069a 100644
--- a/docs/docsite/rst/playbooks_vault.rst
+++ b/docs/docsite/rst/playbooks_vault.rst
@@ -55,7 +55,7 @@ As of version 2.3, Ansible can now use a vaulted variable that lives in an other
               34623731376664623134383463316265643436343438623266623965636363326136
     other_plain_text: othervalue
 
-To create a vaulted variable, use the :ref:`ansible-vault encrypt_string` command. See :ref:`encrypt_string` for details.
+To create a vaulted variable, use the :ref:`ansible-vault encrypt_string <ansible_vault_encrypt_string>` command. See :ref:`encrypt_string` for details.
 
 This vaulted variable will be decrypted with the supplied vault secret and used as a normal variable. The ``ansible-vault`` command line supports stdin and stdout for encrypting data on the fly, which can be used from your favorite editor to create these vaulted variables; you just have to be sure to add the ``!vault`` tag so both Ansible and YAML are aware of the need to decrypt. The ``|`` is also required, as vault encryption results in a multi-line string.
 
diff --git a/docs/docsite/rst/vault.rst b/docs/docsite/rst/vault.rst
index 4b7fbcaa8e..8e0f5c61ca 100644
--- a/docs/docsite/rst/vault.rst
+++ b/docs/docsite/rst/vault.rst
@@ -19,7 +19,7 @@ The vault feature can encrypt any structured data file used by Ansible.  This ca
 Ansible tasks, handlers, and so on are also data so these can be encrypted with vault as well. To hide the names of variables that you're using, you can encrypt the task files in their entirety. However, that might be a little too much and could annoy your coworkers :)
 
 The vault feature can also encrypt arbitrary files, even binary files.  If a vault-encrypted file is
-given as the :ref:`src <src>` argument to the :ref:`copy <copy>`, :ref:`template <template>`,
+given as the 'src' argument to the :ref:`copy <copy>`, :ref:`template <template>`,
 :ref:`unarchive <unarchive>`, :ref:`script <script>` or :ref:`assemble <assemble>` modules, the file will be placed at the destination on the target host decrypted (assuming a valid vault password is supplied when running the play).
 
 As of version 2.3, Ansible also supports encrypting single values inside a YAML file, using the `!vault` tag to let YAML and Ansible know it uses special processing. This feature is covered in more details below.
@@ -277,13 +277,6 @@ To specify a vault password in a text file 'dev-password', use the :option:`--va
 There is a config option (:ref:`DEFAULT_VAULT_PASSWORD_FILE`) to specify a vault password file to use
 without requiring the :option:`--vault-password-file <ansible-playbook --vault-password-file>` cli option.
 
-via config
-  :ref:`ANSIBLE_VAULT_PASSWORD_FILE`
-
-  :ref:`ANSIBLE_VAULT_IDENTITY_LIST`
-
-via env
-   TODO
 
 Multiple vault passwords
 ^^^^^^^^^^^^^^^^^^^^^^^^