From 0f4ca877ac91aa4cf56103f967afec65cca629e1 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Thu, 22 Dec 2016 12:26:28 -0500 Subject: [PATCH] many doc fixes removed a bunch of warnings made nicer formatting of new module info --- docsite/rst/become.rst | 2 +- docsite/rst/community.rst | 4 +-- docsite/rst/dev_guide/index.rst | 2 +- docsite/rst/galaxy.rst | 3 +- docsite/rst/intro_configuration.rst | 4 ++- docsite/rst/intro_inventory.rst | 2 ++ docsite/rst/playbooks_best_practices.rst | 6 ++-- docsite/rst/playbooks_filters.rst | 4 +-- docsite/rst/playbooks_roles.rst | 2 +- docsite/rst/playbooks_tests.rst | 3 +- docsite/rst/playbooks_variables.rst | 3 ++ hacking/templates/rst.j2 | 42 +++++++++++++++--------- 12 files changed, 46 insertions(+), 31 deletions(-) diff --git a/docsite/rst/become.rst b/docsite/rst/become.rst index be00e32e61..09a3f7f2a1 100644 --- a/docsite/rst/become.rst +++ b/docsite/rst/become.rst @@ -162,7 +162,7 @@ Ways to resolve this include: file permissions are also secure if you make the connection to the managed machine as root and then use ``become`` to an unprivileged account. -.. warn:: Although the Solaris ZFS filesystem has filesystem ACLs, the ACLs +.. warning:: Although the Solaris ZFS filesystem has filesystem ACLs, the ACLs are not POSIX.1e filesystem acls (they are NFSv4 ACLs instead). Ansible cannot use these ACLs to manage its temp file permissions so you may have to resort to ``allow_world_readable_tmpfiles`` if the remote machines use ZFS. diff --git a/docsite/rst/community.rst b/docsite/rst/community.rst index bfaac87677..f0ffaf1fd4 100644 --- a/docsite/rst/community.rst +++ b/docsite/rst/community.rst @@ -147,8 +147,8 @@ Note that we do keep Ansible to a particular aesthetic, so if you are unclear ab is a good fit or not, having the discussion on the development list is often a lot easier than having to modify a pull request later. -New module developers should read through `http://docs.ansible.com/ansible/dev_guide/developing_modules.html`_ for helpful pointers -and information about running adhoc tests `http://docs.ansible.com/ansible/dev_guide/developing_modules.html#testing-modules`_. +New module developers should read through `developing modules `_ for helpful pointers +and information about running adhoc tests `testing modules `_. When submitting patches, be sure to run the unit tests first ``make tests`` and always use, these are the same basic tests that will automatically run on Shippable when creating the PR. There are more in depth tests in the ``tests/integration`` diff --git a/docsite/rst/dev_guide/index.rst b/docsite/rst/dev_guide/index.rst index cd93dd2da3..b7d0b18325 100644 --- a/docsite/rst/dev_guide/index.rst +++ b/docsite/rst/dev_guide/index.rst @@ -2,7 +2,7 @@ Developer Information ===================== Ansible Developer Guide -````````````` +``````````````````````` Welcome to the Ansible Developer Guide! diff --git a/docsite/rst/galaxy.rst b/docsite/rst/galaxy.rst index 0c030e0429..0e243e6cf3 100644 --- a/docsite/rst/galaxy.rst +++ b/docsite/rst/galaxy.rst @@ -367,8 +367,7 @@ Use the *--branch* option to import a specific branch. If not specified, the def Role name ========= -By default the name given to the role will be derived from the GitHub repository name. However, you can use the *--role-name -option to override this and set the name. +By default the name given to the role will be derived from the GitHub repository name. However, you can use the *--role-name* option to override this and set the name. No wait ======= diff --git a/docsite/rst/intro_configuration.rst b/docsite/rst/intro_configuration.rst index 4625770ce6..a87a7ed615 100644 --- a/docsite/rst/intro_configuration.rst +++ b/docsite/rst/intro_configuration.rst @@ -91,7 +91,8 @@ allow_world_readable_tmpfiles ============================= .. versionadded:: 2.1 -This makes the temporary files created on the machine to be world readable and will issue a warning instead of failing the task. + +This makes the temporary files created on the machine to be world readable and will issue a warning instead of failing the task. It is useful when becoming an unprivileged user:: @@ -1018,6 +1019,7 @@ control_path_dir This is the base directory of the ControlPath sockets. It is the ``%(directory)s`` part of the ``control_path`` option. This defaults to:: + control_path_dir=$HOME/.ansible/cp .. _scp_if_ssh: diff --git a/docsite/rst/intro_inventory.rst b/docsite/rst/intro_inventory.rst index 453577e299..937f723df6 100644 --- a/docsite/rst/intro_inventory.rst +++ b/docsite/rst/intro_inventory.rst @@ -233,7 +233,9 @@ ansible_ssh_extra_args This setting is always appended to the default :command:`ssh` command line. ansible_ssh_pipelining Determines whether or not to use SSH pipelining. This can override the ``pipelining`` setting in :file:`ansible.cfg`. + .. versionadded:: 2.2 + ansible_ssh_executable This setting overrides the default behavior to use the system :command:`ssh`. This can override the ``ssh_executable`` setting in :file:`ansible.cfg`. diff --git a/docsite/rst/playbooks_best_practices.rst b/docsite/rst/playbooks_best_practices.rst index c67feb95f0..fb1ec6416e 100644 --- a/docsite/rst/playbooks_best_practices.rst +++ b/docsite/rst/playbooks_best_practices.rst @@ -71,13 +71,13 @@ The top level of the directory would contain files and directories like so:: .. _alternative_directory_layout: Alternative Directory Layout -```````````````` +```````````````````````````` Alternatively you can put each inventory file with its ``group_vars``/``host_vars`` in a separate directory. This is particularly useful if your ``group_vars``/``host_vars`` don't have that much in common in different environments. The layout could look something like this:: inventories/ production/ - hosts.yml # inventory file for production servers + hosts # inventory file for production servers group_vars/ group1 # here we assign variables to particular groups group2 # "" @@ -86,7 +86,7 @@ Alternatively you can put each inventory file with its ``group_vars``/``host_var hostname2 # "" staging/ - hosts.yml # inventory file for staging environment + hosts # inventory file for staging environment group_vars/ group1 # here we assign variables to particular groups group2 # "" diff --git a/docsite/rst/playbooks_filters.rst b/docsite/rst/playbooks_filters.rst index 07d161ff96..36517d8a8b 100644 --- a/docsite/rst/playbooks_filters.rst +++ b/docsite/rst/playbooks_filters.rst @@ -4,8 +4,8 @@ Jinja2 filters .. contents:: Topics -Filters in Jinja2 are a way of transforming template expressions from one kind of data into another. Jinja2 -ships with many of these. See `builtin filters`_ in the official Jinja2 template documentation. +Filters in Jinja2 are a way of transforming template expressions from one kind of data into another. +Jinja2 ships with many of these. See `builtin filters`_ in the official Jinja2 template documentation. Take into account that filters always execute on the Ansible controller, **not** on the task target, as they manipulate local data. diff --git a/docsite/rst/playbooks_roles.rst b/docsite/rst/playbooks_roles.rst index c654420655..9043e76c51 100644 --- a/docsite/rst/playbooks_roles.rst +++ b/docsite/rst/playbooks_roles.rst @@ -165,7 +165,7 @@ inside another. .. _dynamic_static: Dynamic versus Static Includes -``````````````````````````` +`````````````````````````````` In Ansible 2.0 there were changes on how 'task' includes are processed. The 'play' includes are still 'static' or unchanged. diff --git a/docsite/rst/playbooks_tests.rst b/docsite/rst/playbooks_tests.rst index 3bee9190e0..1ea7de62f7 100644 --- a/docsite/rst/playbooks_tests.rst +++ b/docsite/rst/playbooks_tests.rst @@ -6,8 +6,7 @@ Jinja2 tests Tests in Jinja2 are a way of evaluating template expressions and returning True or False. Jinja2 ships with many of these. See `builtin tests`_ in the official Jinja2 template documentation. -Tests are very similar to filters and are used mostly the same way, but they can also be used in list -processing filters, like C(map()) and C(select()) to choose items in the list. +Tests are very similar to filters and are used mostly the same way, but they can also be used in list processing filters, like C(map()) and C(select()) to choose items in the list. Like filters, tests always execute on the Ansible controller, **not** on the target of a task, as they test local data. diff --git a/docsite/rst/playbooks_variables.rst b/docsite/rst/playbooks_variables.rst index 4f6e770bfa..fdf7681056 100644 --- a/docsite/rst/playbooks_variables.rst +++ b/docsite/rst/playbooks_variables.rst @@ -676,12 +676,15 @@ period, without the rest of the domain. ``play_hosts`` has been deprecated in 2.2, it was the same as the new ``ansible_play_batch`` variable. .. versionadded:: 2.2 + ``ansible_play_hosts`` is the full list of all hosts still active in the current play. .. versionadded:: 2.2 + ``ansible_play_batch`` is available as a list of hostnames that are in scope for the current 'batch' of the play. The batch size is defined by ``serial``, when not set it is equivalent to the whole play (making it the same as ``ansible_play_hosts``). .. versionadded:: 2.3 + ``ansible_playbook_python`` is the path to the python executable used to invoke the Ansible command line tool. These vars may be useful for filling out templates with multiple hostnames or for injecting the list into the rules for a load balancer. diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index 0822a6d41e..1279fd4c32 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -169,26 +169,36 @@ Notes {% endif %} {% if not deprecated %} -Module Status: @{ ','.join(metadata.status) }@ --------------------- +{% set support = { 'core': 'This module is maintained by those with core commit privileges', 'committer': 'This module is supported mainly by the community and is curated by core committers', 'community': 'This module is community maintained without core committer oversight'} %} +{% set module_states = { 'preview': 'it is not guaranteed to have a backwards compatible interface', 'stableinterface': 'the maintainers for this module guarantee that the no backward incompatible interface changes will be made'} %} - {% if metadata.supported_by == 'core' %} +{% if metadata %} +{% if metadata.status %} -This is a Core Module ---------------------- +Status +~~~~~~ -For more information on what this means please read :doc:`modules_core` - - {% else %} - -This module is supported by: @{ metadata.supported_by }@ ------------------------- - -For more information on what this means please read :doc:`modules_extra` - - {% endif %} +{% for cur_state in metadata.status %} +This module is flagged as **@{cur_state}@** which means that @{module_states[cur_state]}@. +{% endfor %} {% endif %} -For help in developing on modules, should you be so inclined, please read :doc:`community`, :doc:`developing_test_pr` and :doc:`developing_modules`. +{% if metadata.supported_by %} +Support +~~~~~~~ + +@{ support[metadata.supported_by] }@ + +{% if metadata.supported_by == 'core' %} +For more information on what this means please read :doc:`modules_core` +{% else %} +For more information on what this means please read :doc:`modules_extra` +{% endif %} + +{% endif %} +{% endif %} +{% endif %} + +For help in developing on modules, should you be so inclined, please read :doc:`community`, :doc:`dev_guide/developing_test_pr` and :doc:`developing_modules`.