diff --git a/docs/bin/testing_formatter.sh b/docs/bin/testing_formatter.sh index 926bde92454..97423199e49 100755 --- a/docs/bin/testing_formatter.sh +++ b/docs/bin/testing_formatter.sh @@ -4,9 +4,13 @@ cat <<- EOF > ../docsite/rst/dev_guide/testing/sanity/index.rst Sanity Tests ============ -The following sanity tests are available as \`\`--test\`\` options for \`\`ansible-test sanity\`\`: - -$(for test in $(../../test/runner/ansible-test sanity --list-tests); do echo "- :doc:\`${test} <${test}>\`"; done) - +The following sanity tests are available as \`\`--test\`\` options for \`\`ansible-test sanity\`\`. This list is also available using \`\`ansible-test sanity --list-tests\`\`. + +.. toctree:: + :maxdepth: 1 + +$(for test in $(../../test/runner/ansible-test sanity --list-tests); do echo " ${test}"; done) + + EOF diff --git a/docs/docsite/rst/community/committer_guidelines.rst b/docs/docsite/rst/community/committer_guidelines.rst index e0457299ba3..ea29572ea0c 100644 --- a/docs/docsite/rst/community/committer_guidelines.rst +++ b/docs/docsite/rst/community/committer_guidelines.rst @@ -1,3 +1,5 @@ +.. _community_committer_guidelines: + Committers Guidelines (for people with commit rights to Ansible on GitHub) `````````````````````````````````````````````````````````````````````````` diff --git a/docs/docsite/rst/community/github_admins.rst b/docs/docsite/rst/community/github_admins.rst index 537a7a7617b..600f83c0011 100644 --- a/docs/docsite/rst/community/github_admins.rst +++ b/docs/docsite/rst/community/github_admins.rst @@ -18,7 +18,7 @@ actually manage the GitHub permissions. Change Branch Permissions for Release ------------------------------------- -When we make releases we make people go through a :doc:`release_manager` to push commits to that +When we make releases we make people go through a :ref:`release_managers` to push commits to that branch. The GitHub admins are responsible for setting the branch so only the Release Manager can commit to the branch when the release process reaches that stage and later opening the branch once the release has been made. The Release manager will let the GitHub Admin know when this needs to be diff --git a/docs/docsite/rst/community/index.rst b/docs/docsite/rst/community/index.rst index c29d9fff4d3..a25222ed4ac 100644 --- a/docs/docsite/rst/community/index.rst +++ b/docs/docsite/rst/community/index.rst @@ -1,3 +1,5 @@ +.. _ansible_community_guide: + *********************** Ansible Community Guide *********************** diff --git a/docs/docsite/rst/community/release_managers.rst b/docs/docsite/rst/community/release_managers.rst index 6f4b5c7d17a..3ad59ead1fa 100644 --- a/docs/docsite/rst/community/release_managers.rst +++ b/docs/docsite/rst/community/release_managers.rst @@ -1,3 +1,6 @@ +.. _release_managers: + + Release Managers ================ diff --git a/docs/docsite/rst/dev_guide/developing_api.rst b/docs/docsite/rst/dev_guide/developing_api.rst index ebe5d07f1ab..abbf3ed1d12 100644 --- a/docs/docsite/rst/dev_guide/developing_api.rst +++ b/docs/docsite/rst/dev_guide/developing_api.rst @@ -1,3 +1,5 @@ +.. _developing_api: + Python API ========== diff --git a/docs/docsite/rst/dev_guide/developing_inventory.rst b/docs/docsite/rst/dev_guide/developing_inventory.rst index aa7a0ad21dd..f84000e297f 100644 --- a/docs/docsite/rst/dev_guide/developing_inventory.rst +++ b/docs/docsite/rst/dev_guide/developing_inventory.rst @@ -1,10 +1,12 @@ +.. _developing_inventory: + Developing Dynamic Inventory Sources ==================================== .. contents:: Topics :local: -As described in :doc:`../intro_dynamic_inventory`, Ansible can pull inventory information from dynamic sources, including cloud sources. You can also create a new dynamic inventory provider by creating a script or program that can output JSON in the correct format when invoked with the proper arguments. There is no restriction on the language used for creating a dynamic inventory provider. +As described in :ref:`dynamic_inventory`, Ansible can pull inventory information from dynamic sources, including cloud sources. You can also create a new dynamic inventory provider by creating a script or program that can output JSON in the correct format when invoked with the proper arguments. There is no restriction on the language used for creating a dynamic inventory provider. .. _inventory_script_conventions: diff --git a/docs/docsite/rst/dev_guide/developing_module_utilities.rst b/docs/docsite/rst/dev_guide/developing_module_utilities.rst index 7a7363f75a7..44799514b34 100644 --- a/docs/docsite/rst/dev_guide/developing_module_utilities.rst +++ b/docs/docsite/rst/dev_guide/developing_module_utilities.rst @@ -1,3 +1,5 @@ +.. _appendix_module_utilities: + Appendix: Module Utilities `````````````````````````` diff --git a/docs/docsite/rst/dev_guide/developing_modules.rst b/docs/docsite/rst/dev_guide/developing_modules.rst index f3e1cb58dfa..ebcff48a6cb 100644 --- a/docs/docsite/rst/dev_guide/developing_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_modules.rst @@ -1,3 +1,5 @@ +.. _developing_modules: + Developing Modules ================== @@ -16,7 +18,7 @@ return information to ansible by printing a JSON string to stdout before exiting. They take arguments in one of several ways which we'll go into as we work through this tutorial. -See :doc:`../modules` for a list of existing modules. +See :ref:`all_modules` for a list of existing modules. Modules can be written in any language and are found in the path specified by :envvar:`ANSIBLE_LIBRARY` or the ``--module-path`` command line option or @@ -31,7 +33,7 @@ develop a module. Ask the following questions: 1. Does a similar module already exist? -There are a lot of existing modules available, you should check out the list of existing modules at :doc:`../modules` +There are a lot of existing modules available, you should check out the list of existing modules at :ref:`modules` 2. Has someone already worked on a similar Pull Request? @@ -93,7 +95,7 @@ The following topics will discuss how to develop and work with modules: .. seealso:: - :doc:`../modules` + :ref:`all_modules` Learn about available modules :doc:`developing_plugins` Learn about developing plugins diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index a2b498386a0..09b3bdb3676 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -188,7 +188,7 @@ The following fields can be used and are all required unless specified otherwise :module: The name of the module. This must be the same as the filename, without the ``.py`` extension. :short_description: - * A short description which is displayed on the :doc:`../list_of_all_modules` page and ``ansible-doc -l``. + * A short description which is displayed on the :ref:`all_modules` page and ``ansible-doc -l``. * As the short description is displayed by ``ansible-doc -l`` without the category grouping it needs enough detail to explain its purpose without the context of the directory structure in which it lives. * Unlike ``description:`` this field should not have a trailing full stop. :description: diff --git a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst index e84eb30e7f5..78d17b7f261 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst @@ -1,3 +1,5 @@ +.. _developing_modules_general_windows: + Windows Ansible Module Development Walkthrough ============================================== 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 2d6a972b0da..645fd83d82f 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst @@ -22,12 +22,12 @@ Although it's tempting to get straight into coding, there are a few things to be * For new modules going into Ansible 2.4 we are raising the bar so they must be PEP 8 compliant. See :doc:`testing_pep8` for more information. * Starting with Ansible version 2.4, all new modules must support Python 2.6 and Python 3.5+. If this is an issue, please contact us (see the "Speak to us" section later in this document to learn how). * All modules shipped with Ansible must be done so under the GPLv3 license. Files under the ``lib/ansible/module_utils/`` directory should be done so under the BSD license. -* Have a look at the existing modules and how they've been named in the :doc:`../list_of_all_modules`, especially in the same functional area (such as cloud, networking, databases). +* Have a look at the existing modules and how they've been named in the :ref:`all_modules`, especially in the same functional area (such as cloud, networking, databases). * 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 `_. - * Starting with Ansible 2.4 all :doc:`../list_of_network_modules` MUST have unit tests. + * Starting with Ansible 2.4 all :ref:`network_modules` MUST have unit tests. Naming Convention @@ -37,7 +37,7 @@ As you may have noticed when looking under ``lib/ansible/modules/`` we support u The directory name should represent the *product* or *OS* name, not the company name. -Each module should have the above (or similar) prefix; see existing :doc:`../list_of_all_modules` for existing examples. +Each module should have the above (or similar) prefix; see existing :ref:`all_modules` for existing examples. **Note:** @@ -61,7 +61,7 @@ Where to get support Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered. -On :doc:`../community` you can find how to: +In the :ref:`ansible_community_guide` you can find how to: * Subscribe to the Mailing Lists - We suggest "Ansible Development List" (for codefreeze info) and "Ansible Announce list" * ``#ansible-devel`` - We have found that IRC ``#ansible-devel`` on FreeNode's IRC network works best for module developers so we can have an interactive dialogue. @@ -93,7 +93,7 @@ And that's it. Before pushing your PR to GitHub it's a good idea to review the :doc:`developing_modules_checklist` again. -After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :doc:`../YAMLSyntax`) or code that isn't valid Python 2.6 or valid Python 3.5 (see :doc:`developing_python3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review. +After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :ref:`yaml_syntax`) or code that isn't valid Python 2.6 or valid Python 3.5 (see :ref:`developing_python_3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review. If you need further advice, consider join the ``#ansible-devel`` IRC channel (see how in the "Where to get support"). diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 199b56f5cfa..883fb67557d 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -1,3 +1,5 @@ +.. _developing_plugins: + Developing Plugins ================== @@ -149,7 +151,7 @@ Connection plugins allow Ansible to connect to the target hosts so it can execut 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 :doc:`../intro_getting_started` section. +The basics of these connection types are covered in the :ref:`intro_getting_started` section. Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins directory. @@ -362,8 +364,8 @@ When shipped as part of a role, the plugin will be available as soon as the role .. seealso:: - :doc:`../modules` - List of built-in modules + :ref:`all_modules` + List of all modules :doc:`developing_api` Learn about the Python API for task execution :doc:`developing_inventory` 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 4409b5152a7..53f7584eecd 100644 --- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst @@ -211,7 +211,7 @@ the managed machine. complications around Windows modules that must have the same names as Python modules, so that internal calling of modules from other Action Plugins work.) -Much of this functionality comes from the :class:`BaseAction` class, +Much of this functionality comes from the `BaseAction` class, which lives in :file:`plugins/action/__init__.py`. It makes use of ``Connection`` and ``Shell`` objects to do its work. @@ -278,18 +278,18 @@ substitutions: - :code:`"<>"` is substituted with the Ansible version. In :ref:`new-style Python modules ` under the :ref:`Ansiballz` framework the proper way is to instead instantiate an - :class:`AnsibleModule` and then access the version from + `AnsibleModule` and then access the version from :attr:``AnsibleModule.ansible_version``. - :code:`"<>"` is substituted with a string which is the Python ``repr`` of the :term:`JSON` encoded module parameters. Using ``repr`` on the JSON string makes it safe to embed in a Python file. In new-style Python modules under the Ansiballz framework - this is better accessed by instantiating an :class:`AnsibleModule` and + this is better accessed by instantiating an `AnsibleModule` and then using :attr:`AnsibleModule.params`. - :code:`<>` substitutes a string which is a comma separated list of file systems which have a file system dependent security context in SELinux. In new-style Python modules, if you really - need this you should instantiate an :class:`AnsibleModule` and then use + need this you should instantiate an `AnsibleModule` and then use :attr:`AnsibleModule._selinux_special_fs`. The variable has also changed from a comma separated string of file system names to an actual python list of filesystem names. @@ -302,7 +302,7 @@ substitutions: ``syslog_facility`` which was named in :file:`ansible.cfg` or any ``ansible_syslog_facility`` inventory variable that applies to this host. In new-style Python modules this has changed slightly. If you really need to - access it, you should instantiate an :class:`AnsibleModule` and then use + access it, you should instantiate an `AnsibleModule` and then use :attr:`AnsibleModule._syslog_facility` to access it. It is no longer the actual syslog facility and is now the name of the syslog facility. See the :ref:`documentation on internal arguments ` @@ -365,7 +365,7 @@ it parses this string and places the args into other code. .. note:: - Internally, the :class:`AnsibleModule` uses the helper function, + Internally, the `AnsibleModule` uses the helper function, :py:func:`ansible.module_utils.basic._load_params`, to load the parameters from stdin and save them into an internal global variable. Very dynamic custom modules which need to parse the parameters prior to instantiating @@ -395,7 +395,7 @@ This is a boolean. If it's True then the playbook specified ``no_log`` (in a task's parameters or as a play parameter). This automatically affects calls to :py:meth:`AnsibleModule.log`. If a module implements its own logging then it needs to check this value. The best way to look at this is for the module -to instantiate an :class:`AnsibleModule` and then check the value of +to instantiate an `AnsibleModule` and then check the value of :attr:`AnsibleModule.no_log`. .. note:: @@ -410,7 +410,7 @@ the messages are only logged if this is True. This also turns on logging of external commands that the module executes. This can be changed via the ``debug`` setting in :file:`ansible.cfg` or the environment variable :envvar:`ANSIBLE_DEBUG`. If, for some reason, a module must access this, it -should do so by instantiating an :class:`AnsibleModule` and accessing +should do so by instantiating an `AnsibleModule` and accessing :attr:`AnsibleModule._debug`. _ansible_diff @@ -419,7 +419,7 @@ _ansible_diff This boolean is turned on via the ``--diff`` command line option. If a module supports it, it will tell the module to show a unified diff of changes to be made to templated files. The proper way for a module to access this is by -instantiating an :class:`AnsibleModule` and accessing +instantiating an `AnsibleModule` and accessing :attr:`AnsibleModule._diff`. _ansible_verbosity @@ -432,7 +432,7 @@ _ansible_selinux_special_fs ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is a list of names of filesystems which should have a special selinux -context. They are used by the :class:`AnsibleModule` methods which operate on +context. They are used by the `AnsibleModule` methods which operate on files (changing attributes, moving, and copying). The list of names is set via a comma separated string of filesystem names from :file:`ansible.cfg`:: @@ -458,7 +458,7 @@ This parameter controls which syslog facility ansible module logs to. It may be set by changing the ``syslog_facility`` value in :file:`ansible.cfg`. Most modules should just use :meth:`AnsibleModule.log` which will then make use of this. If a module has to use this on its own, it should instantiate an -:class:`AnsibleModule` and then retrieve the name of the syslog facility from +`AnsibleModule` and then retrieve the name of the syslog facility from :attr:`AnsibleModule._syslog_facility`. The code will look slightly different than it did under :ref:`module_replacer` due to how hacky the old way was @@ -480,7 +480,7 @@ _ansible_version ~~~~~~~~~~~~~~~~ This parameter passes the version of ansible that runs the module. To access -it, a module should instantiate an :class:`AnsibleModule` and then retrieve it +it, a module should instantiate an `AnsibleModule` and then retrieve it from :attr:`AnsibleModule.ansible_version`. This replaces :attr:`ansible.module_utils.basic.ANSIBLE_VERSION` from :ref:`module_replacer`. diff --git a/docs/docsite/rst/dev_guide/developing_python3.rst b/docs/docsite/rst/dev_guide/developing_python3.rst index 86913e42cde..5fdd050f366 100644 --- a/docs/docsite/rst/dev_guide/developing_python3.rst +++ b/docs/docsite/rst/dev_guide/developing_python3.rst @@ -1,3 +1,5 @@ +.. _developing_python_3: + ==================== Ansible and Python 3 ==================== diff --git a/docs/docsite/rst/dev_guide/index.rst b/docs/docsite/rst/dev_guide/index.rst index 228014ed8e1..ef37553dcca 100644 --- a/docs/docsite/rst/dev_guide/index.rst +++ b/docs/docsite/rst/dev_guide/index.rst @@ -24,6 +24,6 @@ To get started, select one of the following topics. developing_rebasing testing repomerge - ../release_and_maintenance - ../committer_guidelines + ../reference_appendices/release_and_maintenance + ../community/committer_guidelines ./style_guide/index diff --git a/docs/docsite/rst/dev_guide/testing/compile/index.rst b/docs/docsite/rst/dev_guide/testing/compile/index.rst deleted file mode 100644 index c7444ae1873..00000000000 --- a/docs/docsite/rst/dev_guide/testing/compile/index.rst +++ /dev/null @@ -1,4 +0,0 @@ -Compile Tests -============= - -See :doc:`../../testing_compile` for more information. diff --git a/docs/docsite/rst/dev_guide/testing_sanity.rst b/docs/docsite/rst/dev_guide/testing_sanity.rst index b017162a588..f1c3acf2c32 100644 --- a/docs/docsite/rst/dev_guide/testing_sanity.rst +++ b/docs/docsite/rst/dev_guide/testing_sanity.rst @@ -73,3 +73,5 @@ yamllint ~~~~~~~~ Check YAML files for syntax and formatting issues. + + diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst index 24e9b575d7f..eafef053023 100644 --- a/docs/docsite/rst/index.rst +++ b/docs/docsite/rst/index.rst @@ -15,9 +15,9 @@ We believe simplicity is relevant to all sizes of environments, so we design for Ansible manages machines in an agent-less manner. There is never a question of how to upgrade remote daemons or the problem of not being able to manage systems because daemons are uninstalled. Because OpenSSH is one of the most peer-reviewed open source components, security exposure is greatly reduced. Ansible is decentralized--it relies on your existing OS credentials to control access to remote machines. If needed, Ansible can easily connect with Kerberos, LDAP, and other centralized authentication management systems. -This documentation covers the current released version of Ansible (2.3) and also some development version features (2.4). For recent features, we note in each section the version of Ansible where the feature was added. +This documentation covers the current released version of Ansible (2.5) and also some development version features. For recent features, we note in each section the version of Ansible where the feature was added. -Ansible, Inc. releases a new major release of Ansible approximately every two months. The core application evolves somewhat conservatively, valuing simplicity in language design and setup. However, the community around new modules and plugins being developed and contributed moves very quickly, typically adding 20 or so new modules in each release. +Ansible releases a new major release of Ansible approximately every two months. The core application evolves somewhat conservatively, valuing simplicity in language design and setup. However, the community around new modules and plugins being developed and contributed moves very quickly, adding many new modules in each release. .. toctree:: @@ -80,6 +80,7 @@ Ansible, Inc. releases a new major release of Ansible approximately every two mo reference_appendices/python_3_support reference_appendices/release_and_maintenance reference_appendices/test_strategies + dev_guide/testing/sanity/index reference_appendices/faq reference_appendices/glossary reference_appendices/tower diff --git a/docs/docsite/rst/installation_guide/intro_configuration.rst b/docs/docsite/rst/installation_guide/intro_configuration.rst index 93165896d25..530ae8b4a0e 100644 --- a/docs/docsite/rst/installation_guide/intro_configuration.rst +++ b/docs/docsite/rst/installation_guide/intro_configuration.rst @@ -1,3 +1,5 @@ +.. _intro_configuration: + ******************* Configuring Ansible ******************* @@ -29,9 +31,9 @@ default settings in Ansible. An `example file is available on Github `_. -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 :doc:`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`. 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 :doc:`_config`. +For in-depth details, see :ref:`config`. Environmental configuration diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 344832cd79d..0c6959db684 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -1,3 +1,6 @@ +.. _installation_guide: +.. _intro_installation_guide: + Installation Guide ================== @@ -85,7 +88,7 @@ default this uses sftp. If that's not available, you can switch to scp in By default, Ansible uses Python 2 in order to maintain compatibility with older distributions such as RHEL 6. However, some Linux distributions (Gentoo, Arch) may not have a Python 2.X interpreter installed by default. On those systems, you should install one, and set - the 'ansible_python_interpreter' variable in inventory (see :doc:`intro_inventory`) to point at your 2.X Python. Distributions + the 'ansible_python_interpreter' variable in inventory (see :ref:`inventory`) to point at your 2.X Python. Distributions like Red Hat Enterprise Linux, CentOS, Fedora, and Ubuntu all have a 2.X interpreter installed by default and this does not apply to those distributions. This is also true of nearly all Unix systems. @@ -363,7 +366,7 @@ Ansible's own modules. $ git submodule update --init --recursive Once running the env-setup script you'll be running from checkout and the default inventory file -will be /etc/ansible/hosts. You can optionally specify an inventory file (see :doc:`intro_inventory`) +will be /etc/ansible/hosts. You can optionally specify an inventory file (see :ref:`inventory`) other than /etc/ansible/hosts: .. code-block:: bash @@ -397,9 +400,9 @@ bugs and feature ideas. .. seealso:: - :doc:`intro_adhoc` + :ref:`intro_adhoc` Examples of basic commands - :doc:`playbooks` + :ref:`working_with_playbooks` Learning ansible's configuration management language `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/plugins/plugins.rst b/docs/docsite/rst/plugins/plugins.rst index a971954feba..bc556c4a454 100644 --- a/docs/docsite/rst/plugins/plugins.rst +++ b/docs/docsite/rst/plugins/plugins.rst @@ -1,3 +1,5 @@ +.. _plugins_lookup: + ******************** Working With Plugins ******************** diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst index 56b8851d03c..963c45b7fbc 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst @@ -392,5 +392,5 @@ Connection plugins Porting custom scripts ====================== -Custom scripts that used the ``ansible.runner.Runner`` API in 1.x have to be ported in 2.x. Please refer to: :doc:`dev_guide/developing_api` +Custom scripts that used the ``ansible.runner.Runner`` API in 1.x have to be ported in 2.x. Please refer to: :ref:`developing_api` diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.3.rst b/docs/docsite/rst/porting_guides/porting_guide_2.3.rst index cf2bebfad1d..fdda0fb6369 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.3.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.3.rst @@ -26,7 +26,7 @@ In Ansible 2.2 (and possibly earlier) the `async:` keyword could not be used in **NEW** In Ansible 2.3: -.. code-block:: yaml +.. code-block:: guess - name: Install nginx asynchronously service: @@ -43,7 +43,7 @@ The `ansible_distribution_release` and `ansible_distribution_version` facts on O **OLD** In Ansible 2.2 (and earlier) -.. code-block:: yaml +.. code-block:: guess "ansible_distribution": "OpenBSD" "ansible_distribution_release": "6.0", @@ -52,7 +52,7 @@ The `ansible_distribution_release` and `ansible_distribution_version` facts on O **NEW** In Ansible 2.3: -.. code-block:: yaml +.. code-block:: guess "ansible_distribution": "OpenBSD", "ansible_distribution_release": "release", @@ -68,7 +68,7 @@ Blocks can now have names, this allows you to avoid the ugly `# this block is fo **NEW** In Ansible 2.3: -.. code-block:: yaml +.. code-block:: guess - name: Block test case hosts: localhost @@ -176,7 +176,7 @@ Deprecation of top-level connection arguments **OLD** In Ansible 2.2: -.. code-block:: yaml +.. code-block:: guess - name: example of using top-level options for connection properties ios_command: @@ -189,7 +189,7 @@ Deprecation of top-level connection arguments Will result in: -.. code-block:: yaml +.. code-block:: guess [WARNING]: argument username has been deprecated and will be removed in a future version [WARNING]: argument host has been deprecated and will be removed in a future version @@ -199,7 +199,7 @@ Will result in: **NEW** In Ansible 2.3: -.. code-block:: yaml +.. code-block:: guess - name: Gather facts eos_facts: 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 d6b68effc26..2c5616ca597 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst @@ -99,7 +99,7 @@ In addition to the deprecation warnings, many new tests have been introduced tha when: result is successful -See :doc:`playbooks_tests` for more information. +See :ref:`playbook_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 `_. @@ -271,4 +271,4 @@ NEW In Ansible 2.5 from ansible.module_utils.network.vyos.vyos import get_config, load_config -See the module utilities developer guide see :doc:`dev_guide/developing_module_utilities` for more information. +See the module utilities developer guide see :ref:`appendix_module_utilities` for more information. diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index cb5519682eb..046b3a8c508 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -1,3 +1,6 @@ +.. _yaml_syntax: + + YAML Syntax =========== @@ -8,7 +11,7 @@ We use YAML because it is easier for humans to read and write than other common data formats like XML or JSON. Further, there are libraries available in most programming languages for working with YAML. -You may also wish to read :doc:`playbooks` at the same time to see how this +You may also wish to read :ref:`working_with_playbooks` at the same time to see how this is used in practice. @@ -217,7 +220,7 @@ value:: .. seealso:: - :doc:`playbooks` + :ref:`working_with_playbooks` Learn what playbooks can do and how to write/run them. `YAMLLint `_ YAML Lint (online) helps you debug YAML syntax if you are having problems diff --git a/docs/docsite/rst/reference_appendices/common_return_values.rst b/docs/docsite/rst/reference_appendices/common_return_values.rst index 719c656b22c..638b6e8c158 100644 --- a/docs/docsite/rst/reference_appendices/common_return_values.rst +++ b/docs/docsite/rst/reference_appendices/common_return_values.rst @@ -90,7 +90,7 @@ This key contains a list of dictionaries that will be presented to the user. Key .. seealso:: - :doc:`modules` + :ref:`all_modules` Learn about available modules `GitHub Core modules directory `_ Browse source of core modules diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 8044acfd629..42be3cd2c9c 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -1,3 +1,5 @@ +.. _ansible_faq: + Frequently Asked Questions ========================== @@ -23,8 +25,6 @@ How do I handle different machines needing different user accounts or ports to l Setting inventory variables in the inventory file is the easiest way. -.. include:: ../rst_common/ansible_ssh_changes_note.rst - For instance, suppose these hosts have different usernames and ports: .. code-block:: ini diff --git a/docs/docsite/rst/reference_appendices/galaxy.rst b/docs/docsite/rst/reference_appendices/galaxy.rst index b3b0747d621..56659876f20 100644 --- a/docs/docsite/rst/reference_appendices/galaxy.rst +++ b/docs/docsite/rst/reference_appendices/galaxy.rst @@ -1,3 +1,5 @@ +.. _ansible_galaxy: + Ansible Galaxy ++++++++++++++ @@ -54,7 +56,7 @@ The following provides an example of using *--roles-path* to install the role in .. seealso:: - :doc:`intro_configuration` + :ref:`intro_configuration` All about configuration files version @@ -198,7 +200,7 @@ The complex form can also be used as follows: version: 775396299f2da1f519f0d8885022ca2d6ee80ee8 name: composer -When dependencies are encountered by ``ansible-galaxy``, it will automatically install each dependency to the ``roles_path``. To understand how dependencies are handled during play execution, see :doc:`playbooks_reuse_roles`. +When dependencies are encountered by ``ansible-galaxy``, it will automatically install each dependency to the ``roles_path``. To understand how dependencies are handled during play execution, see :ref:`playbooks_reuse_roles`. .. note:: @@ -507,7 +509,7 @@ Provide the ID of the integration to be disabled. You can find the ID by using t .. seealso:: - :doc:`playbooks_reuse_roles` + :ref:`playbooks_reuse_roles` All about ansible roles `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/reference_appendices/glossary.rst b/docs/docsite/rst/reference_appendices/glossary.rst index cce42f5a947..d17edfe77f3 100644 --- a/docs/docsite/rst/reference_appendices/glossary.rst +++ b/docs/docsite/rst/reference_appendices/glossary.rst @@ -65,7 +65,7 @@ when a term comes up on the mailing list. A conditional is an expression that evaluates to true or false that decides whether a given task is executed on a given machine or not. Ansible's conditionals are powered by the 'when' statement, which are - discussed in the :doc:`playbook documentation `. + discussed in the :ref:`working_with_playbooks`. Declarative An approach to achieving a task that uses a description of the @@ -489,11 +489,11 @@ when a term comes up on the mailing list. .. seealso:: - :doc:`faq` + :ref:`ansible_faq` Frequently asked questions - :doc:`playbooks` + :ref:`working_with_playbooks` An introduction to playbooks - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Best practices advice `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/reference_appendices/python_3_support.rst b/docs/docsite/rst/reference_appendices/python_3_support.rst index fa5412eedfc..b1d9e674630 100644 --- a/docs/docsite/rst/reference_appendices/python_3_support.rst +++ b/docs/docsite/rst/reference_appendices/python_3_support.rst @@ -65,7 +65,7 @@ Testing Python 3 module support [py3-hosts:vars] ansible_python_interpreter=/usr/bin/python3 -See :doc:`intro_inventory` for more information. +See :ref:`intro_inventory` for more information. * Run your command or playbook: @@ -75,7 +75,7 @@ See :doc:`intro_inventory` for more information. $ ansible-playbook sample-playbook.yml -Note that you can also use the :option:`-e` command line option to manually +Note that you can also use the `-e` command line option to manually set the python interpreter when you run a command. For example: .. code-block:: shell @@ -92,5 +92,5 @@ report on `Ansible's GitHub project the bug report so 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 :doc:`dev_guide/developing_python3` for information on how we fix +refer to :ref:`developing_python3` for information on how we fix common Python3 compatibility issues in the Ansible codebase. diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 9bb55ccef8c..cdd25e2dd34 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -1,3 +1,5 @@ +.. _release_and_maintenance: + Release and maintenance ======================= @@ -14,7 +16,7 @@ This cycle can be extended in order to allow for larger changes to be properly implemented and tested before a new release is made available. Ansible has a graduated support structure that extends to three major releases. -For more information, read about the `development and stable version maintenance workflow`_ or see +For more information, read about the :ref: `_development_and_stable_versiona_maintenance_workflow` or see the chart in :ref:`schedule` for the degrees to which current releases are supported. .. note:: Support for three major releases began with Ansible-2.4. Ansible-2.3 and older versions @@ -65,6 +67,7 @@ devel `2.5`_ (unreleased, trunk) In development .. _support_life: .. _methods: +.. _development_and_stable_versiona_maintenance_workflow: Development and stable version maintenance workflow ``````````````````````````````````````````````````` @@ -132,11 +135,11 @@ be delayed in order to allow the new release to be shipped as soon as possible. .. seealso:: - :doc:`committer_guidelines` + :ref:`community_committer_guidelines` Guidelines for Ansible core contributors and maintainers - :doc:`test_strategies` + :ref:`testing_strategies` Testing strategies - :doc:`community` + :ref:`ansible_community_guide` Community information and contributing `Ansible Changelog `_ Documentation of the improvements for each version of Ansible diff --git a/docs/docsite/rst/reference_appendices/test_strategies.rst b/docs/docsite/rst/reference_appendices/test_strategies.rst index 0b2c3f96040..3c8ae98b270 100644 --- a/docs/docsite/rst/reference_appendices/test_strategies.rst +++ b/docs/docsite/rst/reference_appendices/test_strategies.rst @@ -1,3 +1,5 @@ +.. _testing_strategies: + Testing Strategies ================== @@ -142,7 +144,7 @@ a subset of the QA battery against remote nodes. This is what the next section Integrating Testing With Rolling Updates ```````````````````````````````````````` -If you have read into :doc:`playbooks_delegation` it may quickly become apparent that the rolling update pattern can be extended, and you +If you have read into :ref:`playbooks_delegation` it may quickly become apparent that the rolling update pattern can be extended, and you can use the success or failure of the playbook run to decide whether to add a machine into a load balancer or not. This is the great culmination of embedded tests:: @@ -260,11 +262,11 @@ system. .. seealso:: - :doc:`modules` + :ref:`all_modules` All the documentation for Ansible modules - :doc:`playbooks` + :ref:`working_with_playbooks` An introduction to playbooks - :doc:`playbooks_delegation` + :ref:`playbooks_delegation` Delegation, useful for working with load balancers, clouds, and locally executed steps. `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/reference_appendices/tower.rst b/docs/docsite/rst/reference_appendices/tower.rst index 930f4cabb44..6a2f52c6565 100644 --- a/docs/docsite/rst/reference_appendices/tower.rst +++ b/docs/docsite/rst/reference_appendices/tower.rst @@ -1,3 +1,5 @@ +.. _ansible_tower: + Ansible Tower ============= diff --git a/docs/docsite/rst/scenario_guides/guide_aws.rst b/docs/docsite/rst/scenario_guides/guide_aws.rst index 7812ce82401..456a1248c97 100644 --- a/docs/docsite/rst/scenario_guides/guide_aws.rst +++ b/docs/docsite/rst/scenario_guides/guide_aws.rst @@ -141,11 +141,11 @@ Host Inventory `````````````` Once your nodes are spun up, you'll probably want to talk to them again. With a cloud setup, it's best to not maintain a static list of cloud hostnames -in text files. Rather, the best way to handle this is to use the ec2 dynamic inventory script. See :doc:`intro_dynamic_inventory`. +in text files. Rather, the best way to handle this is to use the ec2 dynamic inventory script. See :ref:`dynamic_inventory`. This will also dynamically select nodes that were even created outside of Ansible, and allow Ansible to manage them. -See :doc:`intro_dynamic_inventory` for how to use this, then flip back over to this chapter. +See :ref:`dynamic_inventory` for how to use this, then return to this chapter. .. _aws_tags_and_groups: @@ -190,7 +190,7 @@ Read :ref:`ansible-pull` for more information on pull-mode playbooks. Autoscaling with Ansible Tower `````````````````````````````` -:doc:`tower` also contains a very nice feature for auto-scaling use cases. In this mode, a simple curl script can call +:ref:`ansible_tower` also contains a very nice feature for auto-scaling use cases. In this mode, a simple curl script can call a defined URL and the server will "dial out" to the requester and configure an instance that is spinning up. This can be a great way to reconfigure ephemeral nodes. See the Tower install and product documentation for more details. @@ -241,11 +241,11 @@ documentation for a full list with examples. .. seealso:: - :doc:`modules` + :ref:`all_modules` All the documentation for Ansible modules - :doc:`playbooks` + :ref:`working_with_playbooks` An introduction to playbooks - :doc:`playbooks_delegation` + :ref:`playbooks_delegation` Delegation, useful for working with loud balancers, clouds, and locally executed steps. `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/scenario_guides/guide_rax.rst b/docs/docsite/rst/scenario_guides/guide_rax.rst index f118ec10ea2..c325a2f0d8d 100644 --- a/docs/docsite/rst/scenario_guides/guide_rax.rst +++ b/docs/docsite/rst/scenario_guides/guide_rax.rst @@ -169,7 +169,7 @@ To use the rackspace dynamic inventory script, copy ``rax.py`` into your invento .. note:: Dynamic inventory scripts (like ``rax.py``) are saved in ``/usr/share/ansible/inventory`` if Ansible has been installed globally. If installed to a virtualenv, the inventory scripts are installed to ``$VIRTUALENV/share/inventory``. -.. note:: Users of :doc:`tower` will note that dynamic inventory is natively supported by Tower, and all you have to do is associate a group with your Rackspace Cloud credentials, and it will easily synchronize without going through these steps:: +.. note:: Users of :ref:`ansible_tower` will note that dynamic inventory is natively supported by Tower, and all you have to do is associate a group with your Rackspace Cloud credentials, and it will easily synchronize without going through these steps:: $ RAX_CREDS_FILE=~/.raxpub ansible all -i rax.py -m setup @@ -797,7 +797,7 @@ Advanced Usage Autoscaling with Tower ++++++++++++++++++++++ -:doc:`tower` also contains a very nice feature for auto-scaling use cases. +:ref:`ansible_tower` also contains a very nice feature for auto-scaling use cases. In this mode, a simple curl script can call a defined URL and the server will "dial out" to the requester and configure an instance that is spinning up. This can be a great way to reconfigure ephemeral nodes. See the Tower documentation for more details. diff --git a/docs/docsite/rst/scenario_guides/guide_rolling_upgrade.rst b/docs/docsite/rst/scenario_guides/guide_rolling_upgrade.rst index 2a10cfd3f80..7a3d530fb95 100644 --- a/docs/docsite/rst/scenario_guides/guide_rolling_upgrade.rst +++ b/docs/docsite/rst/scenario_guides/guide_rolling_upgrade.rst @@ -77,7 +77,7 @@ as push updates to all of the servers:: .. note:: - If you're not familiar with terms like playbooks and plays, you should review :doc:`playbooks`. + If you're not familiar with terms like playbooks and plays, you should review :ref:`working_with_playbooks`. In this playbook we have 5 plays. The first one targets ``all`` hosts and applies the ``common`` role to all of the hosts. This is for site-wide things like yum repository configuration, firewall configuration, and anything else that needs to apply to all of the servers. @@ -100,7 +100,7 @@ your roles is up to you and your application, but most sites will have one or mo all systems, and then a series of application-specific roles that install and configure particular parts of the site. Roles can have variables and dependencies, and you can pass in parameters to roles to modify their behavior. -You can read more about roles in the :doc:`playbooks_reuse_roles` section. +You can read more about roles in the :ref:`playbooks_reuse_roles` section. .. _lamp_group_variables: @@ -185,7 +185,7 @@ This loops over all of the hosts in the group called ``monitoring``, and adds an each monitoring hosts' default IPv4 address to the current machine's iptables configuration, so that Nagios can monitor those hosts. You can learn a lot more about Jinja2 and its capabilities `here `_, and you -can read more about Ansible variables in general in the :doc:`playbooks_variables` section. +can read more about Ansible variables in general in the :ref:`playbooks_variables` section. .. _lamp_rolling_upgrade: @@ -269,9 +269,9 @@ Again, if you were using a Netscaler or F5 or Elastic Load Balancer, you would j Managing Other Load Balancers ````````````````````````````` -In this example, we use the simple HAProxy load balancer to front-end the web servers. It's easy to configure and easy to manage. As we have mentioned, Ansible has built-in support for a variety of other load balancers like Citrix NetScaler, F5 BigIP, Amazon Elastic Load Balancers, and more. See the :doc:`modules` documentation for more information. +In this example, we use the simple HAProxy load balancer to front-end the web servers. It's easy to configure and easy to manage. As we have mentioned, Ansible has built-in support for a variety of other load balancers like Citrix NetScaler, F5 BigIP, Amazon Elastic Load Balancers, and more. See the :ref:`working_with_modules` documentation for more information. -For other load balancers, you may need to send shell commands to them (like we do for HAProxy above), or call an API, if your load balancer exposes one. For the load balancers for which Ansible has modules, you may want to run them as a ``local_action`` if they contact an API. You can read more about local actions in the :doc:`playbooks_delegation` section. Should you develop anything interesting for some hardware where there is not a core module, it might make for a good module for core inclusion! +For other load balancers, you may need to send shell commands to them (like we do for HAProxy above), or call an API, if your load balancer exposes one. For the load balancers for which Ansible has modules, you may want to run them as a ``local_action`` if they contact an API. You can read more about local actions in the :ref:`playbooks_delegation` section. Should you develop anything interesting for some hardware where there is not a core module, it might make for a good module for core inclusion! .. _lamp_end_to_end: @@ -282,7 +282,7 @@ Now that you have an automated way to deploy updates to your application, how do Depending on your environment, you might be deploying continuously to a test environment, running an integration test battery against that environment, and then deploying automatically into production. Or you could keep it simple and just use the rolling-update for on-demand deployment into test or production specifically. This is all up to you. -For integration with Continuous Integration systems, you can easily trigger playbook runs using the ``ansible-playbook`` command line tool, or, if you're using :doc:`tower`, the ``tower-cli`` or the built-in REST API. (The tower-cli command 'joblaunch' will spawn a remote job over the REST API and is pretty slick). +For integration with Continuous Integration systems, you can easily trigger playbook runs using the ``ansible-playbook`` command line tool, or, if you're using :ref:`ansible_tower`, the ``tower-cli`` or the built-in REST API. (The tower-cli command 'joblaunch' will spawn a remote job over the REST API and is pretty slick). This should give you a good idea of how to structure a multi-tier application with Ansible, and orchestrate operations upon that app, with the eventual goal of continuous delivery to your customers. You could extend the idea of the rolling upgrade to lots of different parts of the app; maybe add front-end web servers along with application servers, for instance, or replace the SQL database with something like MongoDB or Riak. Ansible gives you the capability to easily manage complicated environments and automate common operations. @@ -290,11 +290,11 @@ This should give you a good idea of how to structure a multi-tier application wi `lamp_haproxy example `_ The lamp_haproxy example discussed here. - :doc:`playbooks` + :ref:`working_with_playbooks` An introduction to playbooks - :doc:`playbooks_reuse_roles` + :ref:`playbooks_reuse_roles` An introduction to playbook roles - :doc:`playbooks_variables` + :ref:`playbooks_variables` An introduction to Ansible variables `Ansible.com: Continuous Delivery `_ An introduction to Continuous Delivery with Ansible diff --git a/docs/docsite/rst/scenario_guides/guide_vagrant.rst b/docs/docsite/rst/scenario_guides/guide_vagrant.rst index e5870bdd85a..646bd764a3b 100644 --- a/docs/docsite/rst/scenario_guides/guide_vagrant.rst +++ b/docs/docsite/rst/scenario_guides/guide_vagrant.rst @@ -18,7 +18,7 @@ If you're not familiar with Vagrant, you should visit `the documentation `_. This guide assumes that you already have Ansible installed and working. -Running from a Git checkout is fine. Follow the :doc:`intro_installation` +Running from a Git checkout is fine. Follow the :ref:`installation_guide` guide for more information. .. _vagrant_setup: @@ -149,6 +149,6 @@ The "Tips and Tricks" chapter of the `Ansible Provisioner documentation The Vagrant documentation for the Ansible provisioner `Vagrant Issue Tracker `_ The open issues for the Ansible provisioner in the Vagrant project - :doc:`playbooks` + :ref:`working_with_playbooks` An introduction to playbooks diff --git a/docs/docsite/rst/scenario_guides/guide_vmware.rst b/docs/docsite/rst/scenario_guides/guide_vmware.rst index 29a01ed0903..52ea70d760c 100644 --- a/docs/docsite/rst/scenario_guides/guide_vmware.rst +++ b/docs/docsite/rst/scenario_guides/guide_vmware.rst @@ -55,6 +55,6 @@ When debugging or creating a new issue, you will need information about your VMw The issue tracker for the pyVmomi project `govc `_ govc is a vSphere CLI built on top of govmomi - :doc:`playbooks` + :ref:`working_with_playbooks` An introduction to playbooks diff --git a/docs/docsite/rst/user_guide/become.rst b/docs/docsite/rst/user_guide/become.rst index 02c1e447137..2ebdae92c52 100644 --- a/docs/docsite/rst/user_guide/become.rst +++ b/docs/docsite/rst/user_guide/become.rst @@ -1,3 +1,5 @@ +.. _become: + ********************************** Understanding Privilege Escalation ********************************** @@ -145,7 +147,7 @@ a potential danger. Ways to resolve this include: -* Use :ref:`pipelining`. When pipelining is enabled, Ansible doesn't save the +* Use `pipelining`. When pipelining is enabled, Ansible doesn't save the module to a temporary file on the client. Instead it pipes the module to the remote python interpreter's stdin. Pipelining does not work for non-python modules. @@ -278,7 +280,6 @@ If a password is required to enter enable mode this can be specified by doing on As a reminder passwords should never be stored in plain text. See how encrypt secrets in vault :doc:`playbooks_vault` for more information. -For more information about ``network_cli`` see :ref:`network-cli`. .. _become-network-auth-and-auth-password: @@ -300,7 +301,7 @@ For network platforms that do not currently support ``connection: network_cli`` authorize: yes auth_pass: " {{ secret_auth_pass }}" -Note that over time more platforms will move to support ``become``. Check the :doc:`list_of_network_modules` for details. +Note that over time more platforms will move to support ``become``. Check the :ref:`network_modules` for details. .. _become-windows: diff --git a/docs/docsite/rst/user_guide/intro_adhoc.rst b/docs/docsite/rst/user_guide/intro_adhoc.rst index b8a9619a0f6..74991ddeedb 100644 --- a/docs/docsite/rst/user_guide/intro_adhoc.rst +++ b/docs/docsite/rst/user_guide/intro_adhoc.rst @@ -1,3 +1,5 @@ +.. _intro_adhoc: + Introduction To Ad-Hoc Commands =============================== @@ -75,13 +77,13 @@ It is also possible to become a user other than root using Rarely, some users have security rules where they constrain their sudo/pbrun/doas environment to running specific command paths only. This does not work with ansible's no-bootstrapping philosophy and hundreds of different modules. If doing this, use Ansible from a special account that does not have this constraint. - One way of doing this without sharing access to unauthorized users would be gating Ansible with :doc:`tower`, which + One way of doing this without sharing access to unauthorized users would be gating Ansible with :ref:`ansible_tower`, which can hold on to an SSH credential and let members of certain organizations use it on their behalf without having direct access. -Ok, so those are basics. If you didn't read about patterns and groups yet, go back and read :doc:`intro_patterns`. +Ok, so those are basics. If you didn't read about patterns and groups yet, go back and read :ref:`intro_patterns`. The ``-f 10`` in the above specifies the usage of 10 simultaneous -processes to use. You can also set this in :doc:`intro_configuration` to avoid setting it again. The default is actually 5, which +processes to use. You can also set this in :ref:`intro_configuration` to avoid setting it again. The default is actually 5, which is really small and conservative. You are probably going to want to talk to a lot more simultaneous hosts so feel free to crank this up. If you have more hosts than the value set for the fork count, Ansible will talk to them, but it will take a little longer. Feel free to push this value as high as your system can handle! @@ -94,7 +96,7 @@ 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 :doc:`modules` page. + instead. Read more about the differences on the :ref:`working_with_modules` page. Using the :ref:`shell` module looks like this:: @@ -266,11 +268,11 @@ Read more about facts at :doc:`playbooks_variables` once you're ready to read up .. seealso:: - :doc:`intro_configuration` + :ref:`intro_configuration` All about the Ansible config file - :doc:`modules` + :ref:`all_modules` A list of available modules - :doc:`playbooks` + :ref:`working_with_playbooks` Using Ansible for configuration management & deployment `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/user_guide/intro_bsd.rst b/docs/docsite/rst/user_guide/intro_bsd.rst index dcc86149757..8300be47fbe 100644 --- a/docs/docsite/rst/user_guide/intro_bsd.rst +++ b/docs/docsite/rst/user_guide/intro_bsd.rst @@ -86,11 +86,11 @@ Please feel free to report any issues or incompatibilities you discover with BSD .. seealso:: - :doc:`intro_adhoc` + :ref:`intro_adhoc` Examples of basic commands - :doc:`playbooks` + :ref:`working_with_playbooks` Learning ansible's configuration management language - :doc:`dev_guide/developing_modules` + :ref:`developing_modules` How to write modules `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst b/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst index adc5cdc8248..08917ed2d85 100644 --- a/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst +++ b/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst @@ -1,3 +1,4 @@ +.. _intro_dynamic_inventory: .. _dynamic_inventory: Working With Dynamic Inventory @@ -7,16 +8,16 @@ Working With Dynamic Inventory Often a user of a configuration management system will want to keep inventory in a different software system. Ansible provides a basic text-based system as described in -:doc:`intro_inventory` but what if you want to use something else? +:ref:`inventory` but what if you want to use something else? Frequent examples include pulling inventory from a cloud provider, LDAP, `Cobbler `_, or a piece of expensive enterprisey CMDB software. Ansible easily supports all of these options via an external inventory system. The contrib/inventory directory contains some of these already -- including options for EC2/Eucalyptus, Rackspace Cloud, and OpenStack, examples of some of which will be detailed below. -:doc:`tower` also provides a database to store inventory results that is both web and REST Accessible. Tower syncs with all Ansible dynamic inventory sources you might be using, and also includes a graphical inventory editor. By having a database record of all of your hosts, it's easy to correlate past event history and see which ones have had failures on their last playbook runs. +:ref:`ansible_tower` also provides a database to store inventory results that is both web and REST Accessible. Tower syncs with all Ansible dynamic inventory sources you might be using, and also includes a graphical inventory editor. By having a database record of all of your hosts, it's easy to correlate past event history and see which ones have had failures on their last playbook runs. -For information about writing your own dynamic inventory source, see :doc:`dev_guide/developing_inventory`. +For information about writing your own dynamic inventory source, see :ref:`developing_inventory`. .. _cobbler_example: diff --git a/docs/docsite/rst/user_guide/intro_getting_started.rst b/docs/docsite/rst/user_guide/intro_getting_started.rst index 87a6a7a002c..eb2d5600864 100644 --- a/docs/docsite/rst/user_guide/intro_getting_started.rst +++ b/docs/docsite/rst/user_guide/intro_getting_started.rst @@ -1,3 +1,5 @@ +.. _intro_getting_started: + Getting Started =============== @@ -8,7 +10,7 @@ Getting Started Foreword ```````` -Now that you've read :doc:`../installation_guide/intro_installation` and installed Ansible, it's time to get +Now that you've read :ref:`intro_installation` and installed Ansible, it's time to get started with some ad-hoc commands. What we are showing first are not the powerful configuration/deployment/orchestration features of Ansible. @@ -28,7 +30,7 @@ By default, Ansible will try to use native OpenSSH for remote communication when possible. This enables ControlPersist (a performance feature), Kerberos, and options in ``~/.ssh/config`` such as Jump Host setup. However, when using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), the version of OpenSSH may be too old to support ControlPersist. On these operating systems, Ansible will fallback into using a high-quality Python implementation of OpenSSH called 'paramiko'. If you wish to use features like Kerberized SSH and more, consider using Fedora, OS X, or Ubuntu as your control machine until a newer version of OpenSSH is available for your platform. -Occasionally you'll encounter a device that doesn't support SFTP. This is rare, but should it occur, you can switch to SCP mode in :doc:`intro_configuration`. +Occasionally you'll encounter a device that doesn't support SFTP. This is rare, but should it occur, you can switch to SCP mode in :ref:`intro_configuration`. When speaking with remote machines, Ansible by default assumes you are using SSH keys. SSH keys are encouraged but password authentication can also be used where needed by supplying the option ``--ask-pass``. If using sudo features and when sudo requires a password, also supply ``--ask-become-pass`` (previously ``--ask-sudo-pass`` which has been deprecated). @@ -145,15 +147,15 @@ Also note that host key checking in paramiko mode is reasonably slow, therefore Ansible will log some information about module arguments on the remote system in the remote syslog, unless a task or play is marked with a "no_log: True" attribute. This is explained later. -To enable basic logging on the control machine see :doc:`intro_configuration` document and set the 'log_path' configuration file setting. Enterprise users may also be interested in :doc:`tower`. Tower provides a very robust database logging feature where it is possible to drill down and see history based on hosts, projects, and particular inventories over time -- explorable both graphically and through a REST API. +To enable basic logging on the control machine see :ref:`intro_configuration` document and set the 'log_path' configuration file setting. Enterprise users may also be interested in :ref:`ansible_tower`. Tower provides a very robust database logging feature where it is possible to drill down and see history based on hosts, projects, and particular inventories over time -- explorable both graphically and through a REST API. .. seealso:: - :doc:`intro_inventory` + :ref:`intro_inventory` More information about inventory - :doc:`intro_adhoc` + :ref:`intro_adhoc` Examples of basic commands - :doc:`playbooks` + :ref:`working_with_playbooks` Learning Ansible's configuration management language `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/user_guide/intro_inventory.rst b/docs/docsite/rst/user_guide/intro_inventory.rst index 55ffe084c88..b5202a319a7 100644 --- a/docs/docsite/rst/user_guide/intro_inventory.rst +++ b/docs/docsite/rst/user_guide/intro_inventory.rst @@ -1,5 +1,7 @@ +.. _intro_inventory: .. _inventory: + Working with Inventory ====================== @@ -11,7 +13,7 @@ which defaults to being saved in the location ``/etc/ansible/hosts``. You can specify a different inventory file using the ``-i `` option on the command line. Not only is this inventory configurable, but you can also use multiple inventory files at the same time and -pull inventory from dynamic or cloud sources or different formats (YAML, ini, etc), as described in :doc:`intro_dynamic_inventory`. +pull inventory from dynamic or cloud sources or different formats (YAML, ini, etc), as described in :ref:`intro_dynamic_inventory`. Introduced in version 2.4, Ansible has inventory plugins to make this flexible and customizable. .. _inventoryformat: @@ -22,7 +24,7 @@ Hosts and Groups The inventory file can be in one of many formats, depending on the inventory plugins you have. For this example, the format for ``/etc/ansible/hosts`` is an INI-like (one of Ansible's defaults) and looks like this: -.. code-block:: ini +.. code-block:: guess mail.example.com @@ -65,7 +67,7 @@ Ports listed in your SSH config file won't be used with the `paramiko` connectio To make things explicit, it is suggested that you set them if things are not running on the default port: -.. code-block:: ini +.. code-block:: guess badwolf.example.com:5309 @@ -74,7 +76,7 @@ You can also describe hosts via variables: In INI: -.. code-block:: ini +.. code-block:: guess jumper ansible_port=5555 ansible_host=192.0.2.50 @@ -98,24 +100,21 @@ Generally speaking, this is not the best way to define variables that describe y If you are adding a lot of hosts following similar patterns, you can do this rather than listing each hostname: -.. code-block:: ini +.. code-block:: guess [webservers] www[01:50].example.com For numeric patterns, leading zeros can be included or removed, as desired. Ranges are inclusive. You can also define alphabetic ranges: -.. code-block:: ini +.. code-block:: guess [databases] db-[a:f].example.com - -.. include:: ../rst_common/ansible_ssh_changes_note.rst - You can also select the connection type and user on a per host basis: -.. code-block:: ini +.. code-block:: guess [targets] @@ -132,7 +131,7 @@ Host Variables As described above, it is easy to assign variables to hosts that will be used later in playbooks: -.. code-block:: ini +.. code-block:: guess [atlanta] host1 http_port=80 maxRequestsPerChild=808 @@ -147,7 +146,7 @@ Variables can also be applied to an entire group at once: The INI way: -.. code-block:: ini +.. code-block:: guess [atlanta] host1 @@ -180,7 +179,7 @@ It is also possible to make groups of groups using the ``:children`` suffix in I You can apply variables using ``:vars`` or ``vars:``: -.. code-block:: ini +.. code-block:: guess [atlanta] host1 @@ -259,7 +258,7 @@ The preferred practice in Ansible is to not store variables in the main inventor In addition to storing variables directly in the inventory file, host and group variables can be stored in individual files relative to the inventory file (not directory, it is always the file). These variable files are in YAML format. Valid file extensions include '.yml', '.yaml', '.json', or no file extension. -See :doc:`YAMLSyntax` if you are new to YAML. +See :ref:`yaml_syntax` if you are new to YAML. Assuming the inventory file path is:: @@ -340,9 +339,6 @@ Host connection: ansible_connection Connection type to the host. This can be the name of any of ansible's connection plugins. SSH protocol types are ``smart``, ``ssh`` or ``paramiko``. The default is smart. Non-SSH based types are described in the next section. - -.. include:: ../rst_common/ansible_ssh_changes_note.rst - General for all connections: ansible_host @@ -473,11 +469,11 @@ Here is an example of how to instantly deploy to created containers:: .. seealso:: - :doc:`intro_dynamic_inventory` + :ref:`intro_dynamic_inventory` Pulling inventory from dynamic sources, such as cloud providers - :doc:`intro_adhoc` + :ref:`intro_adhoc` Examples of basic commands - :doc:`playbooks` + :ref:`working_with_playbooks` Learning Ansible's configuration, deployment, and orchestration language. `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/user_guide/intro_patterns.rst b/docs/docsite/rst/user_guide/intro_patterns.rst index 3dca1a4bf5d..87b95f2853d 100644 --- a/docs/docsite/rst/user_guide/intro_patterns.rst +++ b/docs/docsite/rst/user_guide/intro_patterns.rst @@ -1,3 +1,5 @@ +.. _intro_patterns: + Working with Patterns ===================== diff --git a/docs/docsite/rst/user_guide/modules.rst b/docs/docsite/rst/user_guide/modules.rst index 008c1b77381..88587d6ab09 100644 --- a/docs/docsite/rst/user_guide/modules.rst +++ b/docs/docsite/rst/user_guide/modules.rst @@ -1,3 +1,5 @@ +.. _working_with_modules: + Working With Modules ==================== diff --git a/docs/docsite/rst/user_guide/modules_intro.rst b/docs/docsite/rst/user_guide/modules_intro.rst index 87329d59295..47df4a28763 100644 --- a/docs/docsite/rst/user_guide/modules_intro.rst +++ b/docs/docsite/rst/user_guide/modules_intro.rst @@ -1,3 +1,5 @@ +.. _intro_modules: + Introduction ============ @@ -49,13 +51,13 @@ For a list of all available modules, see :doc:`modules_by_category`, or run the .. seealso:: - :doc:`intro_adhoc` + :ref:`intro_adhoc` Examples of using modules in /usr/bin/ansible - :doc:`playbooks` + :ref:`working_with_playbooks` Examples of using modules with /usr/bin/ansible-playbook - :doc:`dev_guide/developing_modules` + :ref:`developing_modules` How to write your own modules - :doc:`dev_guide/developing_api` + :ref:`developing_api` Examples of using modules with the Python API `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/user_guide/playbooks.rst b/docs/docsite/rst/user_guide/playbooks.rst index a010729b78a..ecd96c93193 100644 --- a/docs/docsite/rst/user_guide/playbooks.rst +++ b/docs/docsite/rst/user_guide/playbooks.rst @@ -1,3 +1,5 @@ +.. _working_with_playbooks: + Working With Playbooks ====================== diff --git a/docs/docsite/rst/user_guide/playbooks_best_practices.rst b/docs/docsite/rst/user_guide/playbooks_best_practices.rst index c7984cfbd9e..9326e429f7c 100644 --- a/docs/docsite/rst/user_guide/playbooks_best_practices.rst +++ b/docs/docsite/rst/user_guide/playbooks_best_practices.rst @@ -1,3 +1,5 @@ +.. _playbooks_best_practices: + Best Practices ============== @@ -491,15 +493,15 @@ This best practice has no limit on the amount of variable and vault files or the .. seealso:: - :doc:`YAMLSyntax` + :ref:`yaml_syntax` Learn about YAML syntax - :doc:`playbooks` + :ref:`working_with_playbooks` Review the basic playbook features - :doc:`modules` + :ref:`all_modules` Learn about available modules - :doc:`dev_guide/developing_modules` + :ref:`developing_modules` Learn how to extend Ansible by writing your own modules - :doc:`intro_patterns` + :ref:`intro_patterns` Learn about how to select hosts `GitHub examples directory `_ Complete playbook files from the github project source diff --git a/docs/docsite/rst/user_guide/playbooks_conditionals.rst b/docs/docsite/rst/user_guide/playbooks_conditionals.rst index f0264e1a2d2..1a461cac085 100644 --- a/docs/docsite/rst/user_guide/playbooks_conditionals.rst +++ b/docs/docsite/rst/user_guide/playbooks_conditionals.rst @@ -1,3 +1,5 @@ +.. _playbooks_conditionals: + Conditionals ============ @@ -140,7 +142,7 @@ If using a dict in a loop:: Loading in Custom Facts ``````````````````````` -It's also easy to provide your own facts if you want, which is covered in :doc:`dev_guide/developing_modules`. To run them, just +It's also easy to provide your own facts if you want, which is covered in :ref:`developing_modules`. To run them, just make a call to your own custom fact gathering module at the top of your list of tasks, and variables returned there will be accessible to future tasks:: @@ -318,7 +320,7 @@ You may check the registered variable's string contents for emptiness:: Commonly Used Facts ``````````````````` -The following Facts (see :ref:`_vars_and_facts`) are frequently used in Conditionals - see above for examples. +The following Facts are frequently used in Conditionals - see above for examples. .. _ansible_distribution: @@ -381,13 +383,13 @@ Possible values:: .. seealso:: - :doc:`playbooks` + :ref:`working_with_playbooks` An introduction to playbooks - :doc:`playbooks_reuse_roles` + :ref:`playbooks_reuse_roles` Playbook organization by roles - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Best practices in playbooks - :doc:`playbooks_variables` + :ref:`playbooks_variables` All about variables `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/playbooks_delegation.rst b/docs/docsite/rst/user_guide/playbooks_delegation.rst index 4fe1d157af0..b1dd0cb26f2 100644 --- a/docs/docsite/rst/user_guide/playbooks_delegation.rst +++ b/docs/docsite/rst/user_guide/playbooks_delegation.rst @@ -1,3 +1,5 @@ +.. _playbooks_delegation: + Delegation, Rolling Updates, and Local Actions ============================================== diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst index 2782f690d0e..0d5d2587055 100644 --- a/docs/docsite/rst/user_guide/playbooks_filters.rst +++ b/docs/docsite/rst/user_guide/playbooks_filters.rst @@ -1,3 +1,5 @@ +.. _playbooks_filters: + Filters ------- diff --git a/docs/docsite/rst/user_guide/playbooks_intro.rst b/docs/docsite/rst/user_guide/playbooks_intro.rst index abf5c691799..54363c3c068 100644 --- a/docs/docsite/rst/user_guide/playbooks_intro.rst +++ b/docs/docsite/rst/user_guide/playbooks_intro.rst @@ -34,7 +34,7 @@ index after you're done with this section. Playbook Language Example ````````````````````````` -Playbooks are expressed in YAML format (see :doc:`YAMLSyntax`) and have a minimum of syntax, which intentionally +Playbooks are expressed in YAML format (see :ref:`yaml_syntax`) and have a minimum of syntax, which intentionally tries to not be a programming language or script, but rather a model of a configuration or a process. Each playbook is composed of one or more 'plays' in a list. @@ -525,17 +525,15 @@ can do this:: .. seealso:: - :doc:`YAMLSyntax` + :ref:`yaml_syntax` Learn about YAML syntax - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Various tips about managing playbooks in the real world - :doc:`index` - Hop back to the documentation index for a lot of special topics about playbooks - :doc:`modules` + :ref:`all_modules` Learn about available modules - :doc:`dev_guide/developing_modules` + :ref:`developing_modules` Learn how to extend Ansible by writing your own modules - :doc:`intro_patterns` + :ref:`intro_patterns` Learn about how to select hosts `Github examples directory `_ Complete end-to-end playbook examples diff --git a/docs/docsite/rst/user_guide/playbooks_lookups.rst b/docs/docsite/rst/user_guide/playbooks_lookups.rst index 73943c81bbd..b0952d6949e 100644 --- a/docs/docsite/rst/user_guide/playbooks_lookups.rst +++ b/docs/docsite/rst/user_guide/playbooks_lookups.rst @@ -36,17 +36,17 @@ One way of using lookups is to populate variables. These macros are evaluated ea - debug: msg: "motd value is {{ motd_value }}" -For more details and a complete list of lookup plugins available, please see :doc:`plugins/lookup`. +For more details and a complete list of lookup plugins available, please see :ref:`plugins_lookup`. .. seealso:: - :doc:`playbooks` + :ref:`working_with_playbooks` An introduction to playbooks - :doc:`playbooks_conditionals` + :ref:`playbooks_conditionals` Conditional statements in playbooks - :doc:`playbooks_variables` + :ref:`playbooks_variables` All about variables - :doc:`playbooks_loops` + :ref:`playbooks_loops` Looping in playbooks `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/playbooks_loops.rst b/docs/docsite/rst/user_guide/playbooks_loops.rst index 8c5732f74f3..70f5f08b610 100644 --- a/docs/docsite/rst/user_guide/playbooks_loops.rst +++ b/docs/docsite/rst/user_guide/playbooks_loops.rst @@ -1,3 +1,5 @@ +.. _playbooks_loops: + Loops ===== @@ -90,10 +92,6 @@ For example, using the 'nested' lookup, you can combine lists:: password: "foo" loop: "{{ lookup('nested', [ 'alice', 'bob' ], [ 'clientdb', 'employeedb', 'providerdb' ]) }}" - -:doc:`Jinja2 lookups playbooks_lookups`, :doc:`filters playbooks_filters` and :doc:`tests playbooks_tests` -make for some powerful data generation and manipulation. - .. note:: ``with_`` loops are actually a combination of things ``with_`` + ``lookup()``, even ``items`` is a lookup. ``loop`` can be used in the same way as shown above. .. _do_until_loops: diff --git a/docs/docsite/rst/user_guide/playbooks_reuse.rst b/docs/docsite/rst/user_guide/playbooks_reuse.rst index 0509c15c2cc..4379cd087c3 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse.rst @@ -1,3 +1,5 @@ +.. _playbooks_reuse: + Creating Reusable Playbooks =========================== @@ -67,17 +69,17 @@ Using ``import*`` can also have some limitations when compared to dynamic includ .. seealso:: - :doc:`playbooks` + :ref:`working_with_playbooks` Review the basic Playbook language features - :doc:`playbooks_variables` + :ref:`playbooks_variables` All about variables in playbooks - :doc:`playbooks_conditionals` + :ref:`playbooks_conditionals` Conditionals in playbooks - :doc:`playbooks_loops` + :ref:`playbooks_loops` Loops in playbooks - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Various tips about managing playbooks in the real world - :doc:`galaxy` + :ref:`ansible_galaxy` How to share roles on galaxy, role management `GitHub Ansible examples `_ Complete playbook files from the GitHub project source diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_includes.rst b/docs/docsite/rst/user_guide/playbooks_reuse_includes.rst index 1bb818e30a4..1cef651f9e4 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse_includes.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse_includes.rst @@ -108,21 +108,21 @@ Please refer to :doc:`playbooks_reuse_roles` for details on including and import .. seealso:: - :doc:`YAMLSyntax` + :ref:`yaml_syntax` Learn about YAML syntax - :doc:`playbooks` + :ref:`working_with_playbooks` Review the basic Playbook language features - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Various tips about managing playbooks in the real world - :doc:`playbooks_variables` + :ref:`playbooks_variables` All about variables in playbooks - :doc:`playbooks_conditionals` + :ref:`playbooks_conditionals` Conditionals in playbooks - :doc:`playbooks_loops` + :ref:`playbooks_loops` Loops in playbooks - :doc:`modules` + :ref:`all_modules` Learn about available modules - :doc:`dev_guide/developing_modules` + :red:`developing_modules` Learn how to extend Ansible by writing your own modules `GitHub Ansible examples `_ Complete playbook files from the GitHub project source diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst index 5bd58198898..6e26157c622 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst @@ -1,3 +1,5 @@ +.. _playbooks_reuse_roles: + Roles ===== @@ -298,7 +300,7 @@ Embedding Modules and Plugins In Roles This is an advanced topic that should not be relevant for most users. -If you write a custom module (see :doc:`dev_guide/developing_modules`) or a plugin (see :doc:`dev_guide/developing_plugins`), you may wish to distribute it as part of a role. +If you write a custom module (see :ref:`developing_modules`) or a plugin (see :ref:`developing_plugins`), you may wish to distribute it as part of a role. Generally speaking, Ansible as a project is very interested in taking high-quality modules into ansible core for inclusion, so this shouldn't be the norm, but it's quite easy to do. A good example for this is if you worked at a company called AcmeWidgets, and wrote an internal module that helped configure your internal software, and you wanted other @@ -345,7 +347,7 @@ Ansible will search for roles in the following way: - A ``roles/`` directory, relative to the playbook file. - By default, in ``/etc/ansible/roles`` -In Ansible 1.4 and later you can configure an additional roles_path to search for roles. Use this to check all of your common roles out to one location, and share them easily between multiple playbook projects. See :doc:`intro_configuration` for details about how to set this up in ansible.cfg. +In Ansible 1.4 and later you can configure an additional roles_path to search for roles. Use this to check all of your common roles out to one location, and share them easily between multiple playbook projects. See :ref:`intro_configuration` for details about how to set this up in ansible.cfg. Ansible Galaxy `````````````` @@ -358,23 +360,23 @@ Read the "About" page on the Galaxy site for more information. .. seealso:: - :doc:`galaxy` + :ref:`ansible_galaxy` How to share roles on galaxy, role management - :doc:`YAMLSyntax` + :ref:`yaml_syntax` Learn about YAML syntax - :doc:`playbooks` + :ref:`working_with_playbooks` Review the basic Playbook language features - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Various tips about managing playbooks in the real world - :doc:`playbooks_variables` + :ref:`playbooks_variables` All about variables in playbooks - :doc:`playbooks_conditionals` + :ref:`playbooks_conditionals` Conditionals in playbooks - :doc:`playbooks_loops` + :ref:`playbooks_loops` Loops in playbooks - :doc:`modules` + :ref:`all_modules` Learn about available modules - :doc:`dev_guide/developing_modules` + :ref:`developing_modules` Learn how to extend Ansible by writing your own modules `GitHub Ansible examples `_ Complete playbook files from the GitHub project source diff --git a/docs/docsite/rst/user_guide/playbooks_roles.rst b/docs/docsite/rst/user_guide/playbooks_roles.rst index 1df49d7688d..94f09cd7cf5 100644 --- a/docs/docsite/rst/user_guide/playbooks_roles.rst +++ b/docs/docsite/rst/user_guide/playbooks_roles.rst @@ -8,10 +8,10 @@ The documentation regarding roles and includes for playbooks have moved. Their n .. seealso:: - :doc:`galaxy` + :ref:`ansible_galaxy` How to share roles on galaxy, role management - :doc:`playbooks` + :ref:`working_with_playbooks` Review the basic Playbook language features - :doc:`playbooks_reuse` + :ref:`playbooks_reuse` Creating reusable Playbooks. diff --git a/docs/docsite/rst/user_guide/playbooks_special_topics.rst b/docs/docsite/rst/user_guide/playbooks_special_topics.rst index 86b17e95742..d2c0d96b800 100644 --- a/docs/docsite/rst/user_guide/playbooks_special_topics.rst +++ b/docs/docsite/rst/user_guide/playbooks_special_topics.rst @@ -9,7 +9,6 @@ and adopt these only if they seem relevant or useful to your environment. :maxdepth: 1 become - playbooks_acceleration playbooks_async playbooks_checkmode playbooks_debugger @@ -17,10 +16,10 @@ and adopt these only if they seem relevant or useful to your environment. playbooks_environment playbooks_error_handling playbooks_advanced_syntax - plugins + ../plugins/plugins playbooks_prompts playbooks_tags playbooks_vault playbooks_startnstep - playbooks_keywords + ../reference_appendices/playbooks_keywords playbooks_lookups diff --git a/docs/docsite/rst/user_guide/playbooks_tests.rst b/docs/docsite/rst/user_guide/playbooks_tests.rst index 9412f804f79..7c3bb7ce5e2 100644 --- a/docs/docsite/rst/user_guide/playbooks_tests.rst +++ b/docs/docsite/rst/user_guide/playbooks_tests.rst @@ -1,3 +1,5 @@ +.. _playbook_tests: + Tests ----- diff --git a/docs/docsite/rst/user_guide/playbooks_variables.rst b/docs/docsite/rst/user_guide/playbooks_variables.rst index 615d05fb32e..d11bccc2b3e 100644 --- a/docs/docsite/rst/user_guide/playbooks_variables.rst +++ b/docs/docsite/rst/user_guide/playbooks_variables.rst @@ -1,3 +1,5 @@ +.. _playbooks_variables: + Variables ========= @@ -148,7 +150,7 @@ Hey Wait, A YAML Gotcha ``````````````````````` YAML syntax requires that if you start a value with ``{{ foo }}`` you quote the whole line, since it wants to be -sure you aren't trying to start a YAML dictionary. This is covered on the :doc:`YAMLSyntax` page. +sure you aren't trying to start a YAML dictionary. This is covered on the :ref:`yaml_syntax` documentation. This won't work:: @@ -839,8 +841,6 @@ a use for it. If multiple variables of the same name are defined in different places, they get overwritten in a certain order. -.. include:: ../rst_common/ansible_ssh_changes_note.rst - In 1.x, the precedence is as follows (with the last listed variables winning prioritization): * "role defaults", which lose in priority to everything and are the most easily overridden @@ -942,7 +942,7 @@ First off, group variables are powerful. Site wide defaults should be defined as a ``group_vars/all`` setting. Group variables are generally placed alongside your inventory file. They can also be returned by a dynamic inventory script (see :doc:`intro_dynamic_inventory`) or defined -in things like :doc:`tower` from the UI or API:: +in things like :ref:`ansible_tower` from the UI or API:: --- # file: /etc/ansible/group_vars/all diff --git a/docs/docsite/rst/user_guide/windows_setup.rst b/docs/docsite/rst/user_guide/windows_setup.rst index 84a50322c4a..57e163ffc34 100644 --- a/docs/docsite/rst/user_guide/windows_setup.rst +++ b/docs/docsite/rst/user_guide/windows_setup.rst @@ -32,7 +32,7 @@ requirement. You can use the `Upgrade-PowerShell.ps1