cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Reduce warnings (#39254)

Browse source 
* removes FAQ links; no entries exist for linked config settings

* fixes various anchors and links

* addresses abadger comments, thanks

* marks orphan pages, avoids TOC errors

* adds links for remote_tmp setting to FAQ
This commit is contained in:
Alicia Cozine 2018-04-25 13:18:52 -05:00 committed by Toshio Kuratomi
parent 476d1f818e
commit 4b52a54e18
24 changed files with 65 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/docsite/rst/community/community.rst
View file

@ -1,3 +1,5 @@
:orphan:
Community Information & Contributing
````````````````````````````````````

8
docs/docsite/rst/dev_guide/developing_modules_checklist.rst
View file

@ -33,7 +33,7 @@ The following checklist items are important guidelines for people who want to c
'supported_by': 'community',
'metadata_version': '1.1'}
Read the complete :ref:`module metadata specification <ansible-metadata-block>` for more information.
Read the complete :ref:`module metadata specification <ansible_metadata_block>` for more information.
* Documentation: Make sure it exists
* Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts. This documentation is not meant to teach a total novice, but it also should not be reserved for the Illuminati (hard balance).
@ -100,7 +100,7 @@ Read the complete :ref:`module metadata specification <ansible-metadata-block>`
* Do not use wildcards for importing other python modules (ex: ``from ansible.module_utils.basic import *``). This used to be required for code imported from ``ansible.module_utils`` but, from Ansible-2.1 onwards, it's just an outdated and bad practice.
* The module must have a `main` function that wraps the normal execution.
* Call your :func:`main` from a conditional so that it would be possible to
import them into unittests in the future example
import them into unit tests in the future example
.. code-block:: python
@ -119,8 +119,8 @@ Read the complete :ref:`module metadata specification <ansible-metadata-block>`
fields of a dictionary and return the dictionary.
* When fetching URLs, please use either fetch_url or open_url from ansible.module_utils.urls
rather than urllib2; urllib2 does not natively verify TLS certificates and so is insecure for https.
* facts modules must return facts in the ansible_facts field of the result
dictionary. :ref:`module_provided_facts`
* facts modules must return facts in the ansible_facts field of the :ref:`result
dictionary<common_return_values>`.
* modules that are purely about fact gathering need to implement check_mode.
they should not cause any changes anyway so it should be as simple as adding
check_mode=True when instantiating AnsibleModule. (The reason is that

2
docs/docsite/rst/dev_guide/developing_program_flow_modules.rst
View file

@ -517,7 +517,7 @@ Why pass args over stdin?
Passing arguments via stdin was chosen for the following reasons:
* When combined with :ref:`pipelining`, this keeps the module's arguments from
* When combined with :ref:`ANSIBLE_PIPELINING`, this keeps the module's arguments from
temporarily being saved onto disk on the remote machine. This makes it
harder (but not impossible) for a malicious user on the remote machine to
steal any sensitive information that may be present in the arguments.

2
docs/docsite/rst/dev_guide/testing_running_locally.rst
View file

@ -1,3 +1,5 @@
.. _testing_running_locally:
***************
Testing Ansible
***************

6
docs/docsite/rst/dev_guide/testing_units.rst
View file

@ -164,7 +164,7 @@ See `eos_banner test
for a practical example.
If you are simulating APIs you may find that python placebo is useful. See
doc:`testing_units_modules` for more information.
:ref:`testing_units_modules` for more information.
Code Coverage For New or Updated Unit Tests
@ -189,13 +189,13 @@ Reports can be generated in several different formats:
* ``ansible-test coverage xml`` - XML report.
To clear data between test runs, use the ``ansible-test coverage erase`` command. See
:doc:`testing_units_running_locally` for more information about generating coverage
:ref:`testing_running_locally` for more information about generating coverage
reports.
.. seealso::
:doc:`testing_units_modules`
:ref:`testing_units_modules`
Special considerations for unit testing modules
:doc:`testing_running_locally`
Running tests locally including gathering and reporting coverage data

2
docs/docsite/rst/dev_guide/testing_units_modules.rst
View file

@ -1,3 +1,5 @@
.. _testing_units_modules:
****************************
Unit Testing Ansible Modules
****************************

2
docs/docsite/rst/installation_guide/intro_configuration.rst
View file

@ -31,7 +31,7 @@ default settings in Ansible.
An `example file is available on Github <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_.
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 more details and a full listing of available configurations go to :ref:`configuration_settings<ansible_configuration_settings>`. Starting with Ansible version 2.4, you can use the :ref:`ansible-config` command line utility to list your available options and inspect the current values.
For in-depth details, see :ref:`ansible_configuration_settings`.

8
docs/docsite/rst/installation_guide/intro_installation.rst
View file

@ -68,7 +68,7 @@ later).
* If you have SELinux enabled on remote nodes, you will also want to install
libselinux-python on them before using any copy/file/template related functions in Ansible. You
can use the :ref:`yum` or :ref`dnf` module in Ansible to install this package on remote systems
can use the :ref:`yum module<yum_module>` or :ref:`dnf module<dnf_module>` in Ansible to install this package on remote systems
that do not have it.
* By default, Ansible uses the python interpreter located at :file:`/usr/bin/python` to run its
@ -77,14 +77,14 @@ later).
"module_stdout": "/bin/sh: /usr/bin/python: No such file or directory\r\n"
you can either set the :ref:`ansible_python_interpreter` inventory variable (see
you can either set the :ref:`ansible_python_interpreter<ansible_python_interpreter>` inventory variable (see
:ref:`inventory`) to point at your interpreter or you can install a Python 2 interpreter for
modules to use. You will still need to set :ref:`ansible_python_interpreter` if the Python
modules to use. You will still need to set :ref:`ansible_python_interpreter<ansible_python_interpreter>` if the Python
2 interpreter is not installed to :command:`/usr/bin/python`.
* Ansible's "raw" module (for executing commands in a quick and dirty way) and the script module
don't even need Python installed. So technically, you can use Ansible to install a compatible
version of Python using the :ref:`raw` module, which then allows you to use everything else.
version of Python using the :ref:`raw module<raw_module>`, which then allows you to use everything else.
For example, if you need to bootstrap Python 2 onto a RHEL-based system, you can install it
via

2
docs/docsite/rst/network/user_guide/shared_snippets/SSH_warning.rst
View file

@ -1,2 +1,4 @@
:orphan:
.. warning::
Never store passwords in plain text. We recommend using SSH keys to authenticate SSH connections. Ansible supports ssh-agent to manage your SSH keys. If you must use passwords to authenticate SSH connections, we recommend encrypting them with :ref:`Ansible Vault <playbooks_vault>`.

24
docs/docsite/rst/plugins/connection.rst
View file

@ -1,15 +1,13 @@
.. contents:: Topics
Connection Plugins
------------------
Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time.
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 :ref:`getting started<intro_getting_started>` section.
By default, Ansible ships with several plugins. The most commonly used are the :ref:`paramiko SSH<paramiko_ssh_connection>`, native ssh (just called :ref:`ssh<ssh_connection>`), and :ref:`local<local_connection>` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines.
The basics of these connection types are covered in the :ref:`getting started<intro_getting_started>` section.
.. _ssh_plugins:
@ -26,28 +24,26 @@ Enabling Connection Plugins
You can extend Ansible to support other transports (such as SNMP or message bus) by dropping a custom plugin
into the ``connection_plugins`` directory.
.. _using_connection:
Using Connection Plugins
++++++++++++++++++++++++
The transport can be changed via :ref:`configuration<ansible_configuration_settings>`, in the command line (``-c``, ``--connection``), as a :ref:`keyword<playbooks_keywords>`)
in your play, or by setting a :ref:`variable<behavioral_parameters>`, most often in your inventory.
The transport can be changed via :ref:`configuration<ansible_configuration_settings>`, at the command line (``-c``, ``--connection``), as a :ref:`keyword <playbooks_keywords>` in your play, or by setting a :ref:`variable<behavioral_parameters>`, most often in your inventory.
For example, for Windows machines you might want to use the :doc:`winrm<connection/winrm>` plugin.
Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory hostname<inventory_hostname>` and defaults to find the target host.
Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory hostname<inventory_hostnames_lookup>` and defaults to find the target host.
Plugins are self-documenting. Each plugin should document its configuration options. The following are connection variables common to most connection plugins:
:ref:`ansible_host<ansible_host>`
The name of the host to connect to, if different from the :ref:`inventory hostname<inventory_hostname>`.
:ref:`ansible_port<ansible_port>`
The ssh port number, for :doc:`ssh <connection/ssh>` and :doc:`paramiko_ssh <connection/paramiko_ssh>` it defaults to 22.
:ref:`ansible_user<ansible_user>`
:ref:`ansible_host<magic_variables_and_hostvars>`
The name of the host to connect to, if different from the :ref:`inventory <intro_inventory>` hostname.
:ref:`ansible_port<faq_setting_users_and_ports>`
The ssh port number, for :ref:`ssh <ssh_connection>` and :ref:`paramiko_ssh <paramiko_ssh_connection>` it defaults to 22.
:ref:`ansible_user<faq_setting_users_and_ports>`
The default user name to use for log in. Most plugins default to the 'current user running Ansible'.
Each plugin might also have a specific version of a variable that overrides the general version. For example, :ref:`ansible_ssh_host<ansible_ssh_host>` for the :doc:`ssh <connection/ssh>` plugin.
Each plugin might also have a specific version of a variable that overrides the general version. For example, ``ansible_ssh_host`` for the :ref:`ssh <ssh_connection>` plugin.
.. _connection_plugin_list:

6
docs/docsite/rst/plugins/shell.rst
View file

@ -4,7 +4,7 @@ Shell Plugins
-------------
Shell plugins work to ensure that the basic commands Ansible runs are properly formatted to work with
the target machine and allow the user to configure certain behaviours related to how Ansible executes tasks.
the target machine and allow the user to configure certain behaviors related to how Ansible executes tasks.
.. _enabling_shell:
@ -23,8 +23,8 @@ Using Shell Plugins
+++++++++++++++++++
In addition to the default configuration settings in :ref:`ansible_configuration_settings`, you can use
a 'connection variable' :ref:`ansible_shell_type` to select the plugin to use.
In this case, you will also want to update the :ref:`ansible_executable` to match.
the connection variable :ref:`ansible_shell_type <ansible_shell_type>` to select the plugin to use.
In this case, you will also want to update the :ref:`ansible_shell_executable <ansible_shell_executable>` to match.
You can further control the settings for each plugin via other configuration options
detailed in the plugin themselves (linked below).

2
docs/docsite/rst/plugins/strategy.rst
View file

@ -34,7 +34,7 @@ or in the `ansible.cfg` file:
[defaults]
strategy=linear
You can also specify the strategy plugin in the play via the :ref:`strategy` keyword::
You can also specify the strategy plugin in the play via the :ref:`strategy keyword <playbooks_keywords>` in a play::
- hosts: all
strategy: debug

4
docs/docsite/rst/plugins/vars.rst
View file

@ -8,7 +8,7 @@ Vars plugins inject additional variable data into Ansible runs that did not come
Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4.
The :doc:`host_group_vars <vars/host_group_vars>` plugin shipped with Ansible enables reading variables from :ref:`host_vars` and :ref:`group_vars`.
The :ref:`host_group_vars <host_group_vars_vars>` plugin shipped with Ansible enables reading variables from :ref:`host_variables` and :ref:`group_variables`.
.. _enable_vars:
@ -16,7 +16,7 @@ The :doc:`host_group_vars <vars/host_group_vars>` plugin shipped with Ansible en
Enabling Vars Plugins
+++++++++++++++++++++
You can activate a custom vars plugins by either dropping it into a ``vars_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>`.
You can activate a custom vars plugin by either dropping it into a ``vars_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>`.
.. _using_vars:

4
docs/docsite/rst/porting_guides/porting_guide_2.5.rst
View file

@ -111,7 +111,7 @@ In addition to the deprecation warnings, many new tests have been introduced tha
when: result is successful
See :ref:`playbook_tests` for more information.
See :ref:`playbooks_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 <https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py>`_.
@ -140,7 +140,7 @@ The following modules no longer exist:
* :ref:`cl_license <cl_license_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`cl_interface <cl_interface_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`cl_bond <cl_bond_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`ec2_vpc <ec2_vpc_module>` use :ref:`ec2_vpc_net <ec2_vpc_net_module>` along with supporting modules :ref:`ec2_vpc_igw <ec2_vpc_igw_module>`, :ref:`ec2_vpc_route_table <ec2_vpc_route_table_module>`, :ref:`ec2_vpc_subnet <ec2_vpc_subnet_module>`, :ref:`ec2_vpc_dhcp_options <ec2_vpc_dhcp_options_module>`, :ref:`ec2_vpc_nat_gateway <ec2_vpc_nat_gateway_module>`, :ref:`ec2_vpc_nacl <ec2_vpc_nacl_module>` instead.
* :ref:`ec2_vpc <ec2_vpc_module>` use :ref:`ec2_vpc_net <ec2_vpc_net_module>` along with supporting modules :ref:`ec2_vpc_igw <ec2_vpc_igw_module>`, :ref:`ec2_vpc_route_table <ec2_vpc_route_table_module>`, :ref:`ec2_vpc_subnet <ec2_vpc_subnet_module>`, :ref:`ec2_vpc_dhcp_option <ec2_vpc_dhcp_option_module>`, :ref:`ec2_vpc_nat_gateway <ec2_vpc_nat_gateway_module>`, :ref:`ec2_vpc_nacl <ec2_vpc_nacl_module>` instead.
* :ref:`ec2_ami_search <ec2_ami_search_module>` use :ref:`ec2_ami_facts <ec2_ami_facts_module>` instead
* :ref:`docker <docker_module>` use :ref:`docker_container <docker_container_module>` and :ref:`docker_image <docker_image_module>` instead

3
docs/docsite/rst/porting_guides/porting_guide_2.6.rst
View file

@ -22,8 +22,7 @@ No notable changes.
Deprecated
==========
* In the :ref:`nxos_igmp_interface <nxos_igmp_interface>` module, `oif_prefix` and `oif_source` properties are deprecated. Use
`ois_ps` parameter with a dictionary of prefix and source to values instead.
* In the :ref:`nxos_igmp_interface module<nxos_igmp_interface_module>`, ``oif_prefix`` and ``oif_source`` properties are deprecated. Use ``ois_ps`` parameter with a dictionary of prefix and source to values instead.
Modules
=======

4
docs/docsite/rst/reference_appendices/common_return_values.rst
View file

@ -1,3 +1,5 @@
.. _common_return_values:
Return Values
-------------
@ -11,8 +13,6 @@ This document covers return values common to all modules.
.. note:: Some of these keys might be set by Ansible itself once it processes the module's return information.
.. _common_return_values:
Common
^^^^^^

5
docs/docsite/rst/reference_appendices/faq.rst
View file

@ -19,6 +19,7 @@ Setting environment variables can be done with the `environment` keyword. It can
.. note:: starting in 2.0.1 the setup task from gather_facts also inherits the environment directive from the play, you might need to use the `|default` filter to avoid errors if setting this at play level.
.. _faq_setting_users_and_ports:
How do I handle different machines needing different user accounts or ports to log in with?
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@ -185,12 +186,12 @@ By default, Solaris 10 and earlier run a non-POSIX shell which does not correctl
tmp directory Ansible uses ( :file:`~/.ansible/tmp`). If you see module failures on Solaris machines, this
is likely the problem. There are several workarounds:
* You can set :ref:`remote_tmp` to a path that will expand correctly with the Solaris shell. For
* You can set ``remote_tmp`` to a path that will expand correctly with the shell you are using (see the plugin documentation for :ref:`C shell<csh_shell>`, :ref:`fish shell<fish_shell>`, and :ref:`Powershell<powershell_shell>`). For
example, in the ansible config file you can set::
remote_tmp=$HOME/.ansible/tmp
In Ansible 2.5 and later, you can also set it per-host like this::
In Ansible 2.5 and later, you can also set it per-host in inventory like this::
solaris1 ansible_remote_tmp=$HOME/.ansible/tmp

2
docs/docsite/rst/reference_appendices/python_3_support.rst
View file

@ -88,5 +88,5 @@ If you find a bug running under Python 3 you can submit a bug report on `Ansible
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 :ref:`developing_python3` for information on how we fix
refer to :ref:`developing_python_3` for information on how we fix
common Python3 compatibility issues in the Ansible codebase.

6
docs/docsite/rst/user_guide/intro_inventory.rst
View file

@ -388,9 +388,11 @@ ansible_become_flags
Remote host environment parameters:
.. _ansible_shell_type:
ansible_shell_type
The shell type of the target system. You should not use this setting unless you have set the
:ref:`ansible_shell_executable` to a non-Bourne (sh) compatible shell. By default commands are
:ref:`ansible_shell_executable<ansible_shell_executable>` to a non-Bourne (sh) compatible shell. By default commands are
formatted using ``sh``-style syntax. Setting this to ``csh`` or ``fish`` will cause commands
executed on target systems to follow those shell's syntax instead.
@ -404,7 +406,7 @@ ansible_python_interpreter
be named something like :program:`python2.6`.
ansible_*_interpreter
Works for anything such as ruby or perl and works just like :ref:`ansible_python_interpreter`.
Works for anything such as ruby or perl and works just like :ref:`ansible_python_interpreter<ansible_python_interpreter>`.
This replaces shebang of modules which will run on that host.
.. versionadded:: 2.1

6
docs/docsite/rst/user_guide/modules_support.rst
View file

@ -10,13 +10,13 @@ To help identify maintainers and understand how the included modules are officia
Core
````
:ref:`core_supported`. These are maintained by the Ansible Engineering Team.
:ref:`Core Maintained<core_supported>` modules are maintained by the Ansible Engineering Team.
These modules are integral to the basic foundations of the Ansible distribution.
Network
```````
:ref:`network_supported`. These are maintained by the Ansible Network Team. Please note there are additional networking modules that are categorized as Certified or Community not maintained by Ansible.
:ref:`Network Maintained<network_supported>` modules are are maintained by the Ansible Network Team. Please note there are additional networking modules that are categorized as Certified or Community not maintained by Ansible.
Certified
@ -27,7 +27,7 @@ Certified modules are part of a future planned program currently in development.
Community
`````````
:ref:`community_supported`. These are submitted and maintained by the Ansible community. These modules are not maintained by Ansible, and are included as a convenience.
:ref:`Community Maintained<community_supported>` modules are submitted and maintained by the Ansible community. These modules are not maintained by Ansible, and are included as a convenience.
Issue Reporting
```````````````

2
docs/docsite/rst/user_guide/playbooks_roles.rst
View file

@ -1,3 +1,5 @@
:orphan:
Playbook Roles and Include Statements
=====================================

2
docs/docsite/rst/user_guide/playbooks_strategies.rst
View file

@ -1,3 +1,5 @@
.. _playbooks_strategies:
Strategies
===========

5
docs/templates/modules_by_category.rst.j2 vendored
View file

@ -1,3 +1,8 @@
.. _modules_by_category:
{# avoids rST "isn't included in any toctree" errors for module index docs #}
:orphan:
Module Index
============

3
docs/templates/modules_by_support.rst.j2 vendored
View file

@ -1,5 +1,8 @@
.. _@{ slug }@:
{# avoids rST "isn't included in any toctree" errors for module index docs #}
:orphan:
Modules Maintained by the @{ maintainers }@
``````````````````````````@{ '`' * maintainers | length }@