diff --git a/docs/docsite/rst/community.rst b/docs/docsite/rst/community.rst index b011bd5f65..c0026df50f 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 `_. +* 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 `_. * 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 ` 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 `. .. 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 ` and multiple :option:`--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/modules_support.rst b/docs/docsite/rst/modules_support.rst index 6e48beb410..45cdfee3bb 100644 --- a/docs/docsite/rst/modules_support.rst +++ b/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 `_ or on Ansible’s “#ansible” channel, located on irc.freenode.net. -For development-oriented topics, use the `ansible-devel Google group `_ or Ansible’s #ansible and #ansible-devel channels, located on irc.freenode.net. You should also read :doc:`Community Information & Contributing `, :doc:`Testing Ansible `, and :doc:`Developing Modules `. +For development-oriented topics, use the `ansible-devel Google group `_ or Ansible’s #ansible and #ansible-devel channels, located on irc.freenode.net. You should also read :doc:`Community Information & Contributing `, :doc:`Testing Ansible `, and :doc:`Developing Modules `. The modules are hosted on GitHub in a subdirectory of the `Ansible `_ repo. diff --git a/docs/docsite/rst/playbooks_intro.rst b/docs/docsite/rst/playbooks_intro.rst index 12a2b7109f..0b766af4a2 100644 --- a/docs/docsite/rst/playbooks_intro.rst +++ b/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 ```````````` 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 eaf6013ccf..742059ed7b 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 ` 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 ` argument to the :ref:`copy `, :ref:`template