utilities: Clean up parameter types and add seealso

docs/docsite/rst/user_guide/playbooks_reuse_includes.rst

@@ -1,6 +1,8 @@
 Including and Importing
 =======================
 
+.. _playbooks_reuse_includes:
+
 .. contents:: Topics
 
 Includes vs. Imports

lib/ansible/modules/inventory/add_host.py

@@ -1,81 +1,83 @@
 # -*- mode: python -*-
-#
+
+# Copyright: (c) 2012, Seth Vidal (@skvidal)
 # Copyright: Ansible Team
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: add_host
-short_description: add a host (and alternatively a group) to the ansible-playbook in-memory inventory
+short_description: Add a host (and alternatively a group) to the ansible-playbook in-memory inventory
 description:
-  - Use variables to create new hosts and groups in inventory for use in later plays of the same playbook.
-    Takes variables so you can define the new hosts more fully.
-  - This module is also supported for Windows targets.
+- Use variables to create new hosts and groups in inventory for use in later plays of the same playbook.
+- Takes variables so you can define the new hosts more fully.
+- This module is also supported for Windows targets.
 version_added: "0.9"
 options:
   name:
-    aliases: [ 'hostname', 'host' ]
     description:
     - The hostname/ip of the host to add to the inventory, can include a colon and a port number.
+    type: str
     required: true
+    aliases: [ host, hostname ]
   groups:
-    aliases: [ 'groupname', 'group' ]
     description:
-    - The groups to add the hostname to, comma separated.
-    required: false
+    - The groups to add the hostname to.
+    type: list
+    aliases: [ group, groupname ]
 notes:
-    - This module bypasses the play host loop and only runs once for all the hosts in the play, if you need it
-      to iterate use a with\_ directive.
-    - Windows targets are supported by this module.
-    - The alias 'host' of the parameter 'name' is only available on >=2.4
-    - Since Ansible version 2.4, the ``inventory_dir`` variable is now set to ``None`` instead of the 'global inventory source',
-      because you can now have multiple sources.  An example was added that shows how to partially restore the previous behaviour.
+- This module bypasses the play host loop and only runs once for all the hosts in the play, if you need it
+  to iterate use a with-loop construct.
+- The alias C(host) of the parameter C(name) is only available on Ansible 2.4 and newer.
+- Since Ansible 2.4, the C(inventory_dir) variable is now set to C(None) instead of the 'global inventory source',
+  because you can now have multiple sources.  An example was added that shows how to partially restore the previous behaviour.
+- Windows targets are supported by this module.
+seealso:
+- module: group_by
 author:
-    - "Ansible Core Team"
-    - "Seth Vidal (@skvidal)"
+- Ansible Core Team
+- Seth Vidal (@skvidal)
 '''
 
-EXAMPLES = '''
-- name: add host to group 'just_created' with variable foo=42
+EXAMPLES = r'''
+- name: Add host to group 'just_created' with variable foo=42
   add_host:
-    name: "{{ ip_from_ec2 }}"
+    name: '{{ ip_from_ec2 }}'
     groups: just_created
     foo: 42
 
-- name: add host to multiple groups
+- name: Add host to multiple groups
   add_host:
-    hostname: "{{ new_ip }}"
+    hostname: '{{ new_ip }}'
     groups:
-      - group1
-      - group2
+    - group1
+    - group2
 
-- name: add a host with a non-standard port local to your machines
+- name: Add a host with a non-standard port local to your machines
   add_host:
-    name: "{{ new_ip }}:{{ new_port }}"
+    name: '{{ new_ip }}:{{ new_port }}'
 
-- name: add a host alias that we reach through a tunnel (Ansible <= 1.9)
+- name: Add a host alias that we reach through a tunnel (Ansible 1.9 and older)
   add_host:
-    hostname: "{{ new_ip }}"
-    ansible_ssh_host: "{{ inventory_hostname }}"
-    ansible_ssh_port: "{{ new_port }}"
+    hostname: '{{ new_ip }}'
+    ansible_ssh_host: '{{ inventory_hostname }}'
+    ansible_ssh_port: '{{ new_port }}'
 
-- name: add a host alias that we reach through a tunnel (Ansible >= 2.0)
+- name: Add a host alias that we reach through a tunnel (Ansible 2.0 and newer)
   add_host:
-    hostname: "{{ new_ip }}"
-    ansible_host: "{{ inventory_hostname }}"
-    ansible_port: "{{ new_port }}"
+    hostname: '{{ new_ip }}'
+    ansible_host: '{{ inventory_hostname }}'
+    ansible_port: '{{ new_port }}'
 
-- name: Ensure inventory vars are set to the same value as the inventory_hostname has (close to pre 2.4 behaviour)
+- name: Ensure inventory vars are set to the same value as the inventory_hostname has (close to pre Ansible 2.4 behaviour)
   add_host:
     hostname: charlie
-    inventory_dir: "{{inventory_dir}}"
+    inventory_dir: '{{ inventory_dir }}'
 '''

lib/ansible/modules/inventory/group_by.py

@@ -1,43 +1,46 @@
 # -*- mode: python -*-
-#
+
+# Copyright: (c) 2012, Jeroen Hoekx (@jhoekx)
 # Copyright: Ansible Team
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: group_by
 short_description: Create Ansible groups based on facts
 description:
-  - Use facts to create ad-hoc groups that can be used later in a playbook.
-  - This module is also supported for Windows targets.
+- Use facts to create ad-hoc groups that can be used later in a playbook.
+- This module is also supported for Windows targets.
 version_added: "0.9"
 options:
   key:
     description:
-    - The variables whose values will be used as groups
+    - The variables whose values will be used as groups.
+    type: str
     required: true
   parents:
     description:
-    - The list of the parent groups
-    required: false
-    default: "all"
+    - The list of the parent groups.
+    type: list
+    default: all
     version_added: "2.4"
-author: "Jeroen Hoekx (@jhoekx)"
 notes:
-  - Spaces in group names are converted to dashes '-'.
-  - This module is also supported for Windows targets.
+- Spaces in group names are converted to dashes '-'.
+- This module is also supported for Windows targets.
+seealso:
+- module: add_host
+author:
+- Jeroen Hoekx (@jhoekx)
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 # Create groups based on the machine architecture
 - group_by:
     key: machine_{{ ansible_machine }}
@@ -51,5 +54,4 @@
     key: el{{ ansible_distribution_major_version }}-{{ ansible_architecture }}
     parents:
       - el{{ ansible_distribution_major_version }}
-
 '''

lib/ansible/modules/utilities/helper/_accelerate.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2013, James Cammarata <jcammarata@ansible.com>
+# Copyright: (c) 2013, James Cammarata <jcammarata@ansible.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function

lib/ansible/modules/utilities/helper/meta.py

@@ -1,88 +1,101 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2016, Ansible, a Red Hat company
+# Copyright: (c) 2016, Ansible, a Red Hat company
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 module: meta
 short_description: Execute Ansible 'actions'
-version_added: "1.2"
+version_added: '1.2'
 description:
-    - Meta tasks are a special kind of task which can influence Ansible internal execution or state. Prior to Ansible 2.0,
-      the only meta option available was `flush_handlers`. As of 2.2, there are five meta tasks which can be used.
-      Meta tasks can be used anywhere within your playbook.
+    - Meta tasks are a special kind of task which can influence Ansible internal execution or state.
+    - Prior to Ansible 2.0, the only meta option available was C(flush_handlers).
+    - As of Ansible 2.2, there are five meta tasks which can be used.
+    - Meta tasks can be used anywhere within your playbook.
     - This module is also supported for Windows targets.
 options:
   free_form:
     description:
-        - This module takes a free form command, as a string. There's not an actual option named "free form".  See the examples!
-        - >
-          C(flush_handlers) makes Ansible run any handler tasks which have thus far been notified. Ansible inserts these tasks internally at certain
+        - This module takes a free form command, as a string. There is not an actual option named "free form".  See the examples!
+        - C(flush_handlers) makes Ansible run any handler tasks which have thus far been notified. Ansible inserts these tasks internally at certain
           points to implicitly trigger handler runs (after pre/post tasks, the final role execution, and the main tasks section of your plays).
-        - >
-          C(refresh_inventory) (added in 2.0) forces the reload of the inventory, which in the case of dynamic inventory scripts means they will be
+        - C(refresh_inventory) (added in Ansible 2.0) forces the reload of the inventory, which in the case of dynamic inventory scripts means they will be
           re-executed. If the dynamic inventory script is using a cache, Ansible cannot know this and has no way of refreshing it (you can disable the cache
-          or, if available for your specific inventory datasource (for es.: aws), you can use the an inventory plugin instead of an inventory script).
-          This is mainly useful when additional hosts are created and users wish to use them instead of using the `add_host` module."
-        - "C(noop) (added in 2.0) This literally does 'nothing'. It is mainly used internally and not recommended for general use."
-        - "C(clear_facts) (added in 2.1) causes the gathered facts for the hosts specified in the play's list of hosts to be cleared, including the fact cache."
-        - "C(clear_host_errors) (added in 2.1) clears the failed state (if any) from hosts specified in the play's list of hosts."
-        - "C(end_play) (added in 2.2) causes the play to end without failing the host(s). Note that this affects all hosts."
-        - "C(reset_connection) (added in 2.3) interrupts a persistent connection (i.e. ssh + control persist)"
-        - "C(end_host) (added in 2.8) is a per-host variation of C(end_play). Causes the play to end for the current host without failing it."
-    choices: ['flush_handlers', 'refresh_inventory', 'noop', 'clear_facts', 'clear_host_errors', 'end_play', 'reset_connection', 'end_host']
+          or, if available for your specific inventory datasource (e.g. aws), you can use the an inventory plugin instead of an inventory script).
+          This is mainly useful when additional hosts are created and users wish to use them instead of using the M(add_host) module.
+        - C(noop) (added in Ansible 2.0) This literally does 'nothing'. It is mainly used internally and not recommended for general use.
+        - C(clear_facts) (added in Ansible 2.1) causes the gathered facts for the hosts specified in the play's list of hosts to be cleared,
+          including the fact cache.
+        - C(clear_host_errors) (added in Ansible 2.1) clears the failed state (if any) from hosts specified in the play's list of hosts.
+        - C(end_play) (added in Ansible 2.2) causes the play to end without failing the host(s). Note that this affects all hosts.
+        - C(reset_connection) (added in Ansible 2.3) interrupts a persistent connection (i.e. ssh + control persist)
+        - C(end_host) (added in Ansible 2.8) is a per-host variation of C(end_play). Causes the play to end for the current host without failing it.
+    choices: [ clear_facts, clear_host_errors, end_host, end_play, flush_handlers, noop, refresh_inventory, reset_connection ]
     required: true
 notes:
     - C(meta) is not really a module nor action_plugin as such it cannot be overwritten.
+    - C(clear_facts) will remove the persistent facts from M(set_fact) using C(cacheable=True),
+      but not the current host variable it creates for the current run.
     - This module is also supported for Windows targets.
-    - "C(clear_facts) will remove the persistent facts from ``set_fact: cacheable=True``, but not the current host variable it creates for the current run."
+seealso:
+- module: assert
+- module: fail
 author:
-    - "Ansible Core Team"
+    - Ansible Core Team
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
+# Example showing flushing handlers on demand, not at end of play
 - template:
     src: new.j2
     dest: /etc/config.txt
   notify: myhandler
-- name: force all notified handlers to run at this point, not waiting for normal sync points
+
+- name: Force all notified handlers to run at this point, not waiting for normal sync points
   meta: flush_handlers
 
-- name: reload inventory, useful with dynamic inventories when play makes changes to the existing hosts
+# Example showing how to refresh inventory during play
+- name: Reload inventory, useful with dynamic inventories when play makes changes to the existing hosts
   cloud_guest:            # this is fake module
     name: newhost
     state: present
+
 - name: Refresh inventory to ensure new instances exist in inventory
   meta: refresh_inventory
 
+# Example showing how to clear all existing facts of targetted hosts
 - name: Clear gathered facts from all currently targeted hosts
   meta: clear_facts
 
-- name: bring host back to play after failure
+# Example showing how to continue using a failed target
+- name: Bring host back to play after failure
   copy:
     src: file
     dest: /etc/file
   remote_user: imightnothavepermission
 
 - meta: clear_host_errors
 
-- user: name={{ansible_user}} groups=input
-- name: reset ssh connection to allow user changes to affect 'current login user'
+# Example showing how to reset an existing connection
+- user:
+    name: '{{ ansible_user }}'
+    groups: input
+
+- name: Reset ssh connection to allow user changes to affect 'current login user'
   meta: reset_connection
 
+# Example showing how to end the play for specific targets
 - name: End the play for hosts that run CentOS 6
   meta: end_host
   when:
-    - ansible_distribution == 'CentOS'
-    - ansible_distribution_major_version == '6'
+  - ansible_distribution == 'CentOS'
+  - ansible_distribution_major_version == '6'
 '''