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.

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

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.
 
 

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

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

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:
 

docs/docsite/rst/modules_support.rst

@@ -34,7 +34,7 @@ If you believe you have found a bug in a module and are already running the late
 
 Should you have a question rather than a bug report, inquiries are welcome on the `ansible-project Google group <https://groups.google.com/forum/#%21forum/ansible-project>`_ or on Ansible’s “#ansible” channel, located on irc.freenode.net.
 
-For development-oriented topics, use the `ansible-devel Google group <https://groups.google.com/forum/#%21forum/ansible-devel>`_ or Ansible’s #ansible and #ansible-devel channels, located on irc.freenode.net. You should also read :doc:`Community Information & Contributing <community>`, :doc:`Testing Ansible <testing>`, and :doc:`Developing Modules <developing_modules>`.
+For development-oriented topics, use the `ansible-devel Google group <https://groups.google.com/forum/#%21forum/ansible-devel>`_ or Ansible’s #ansible and #ansible-devel channels, located on irc.freenode.net. You should also read :doc:`Community Information & Contributing <community>`, :doc:`Testing Ansible <dev_guide/testing>`, and :doc:`Developing Modules <dev_guide/developing_modules>`.
 
 The modules are hosted on GitHub in a subdirectory of the `Ansible <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_ repo.
 

docs/docsite/rst/playbooks_intro.rst

@@ -482,7 +482,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
 ````````````

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

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

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

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.
 

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

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.
 

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