Unifying wording and formatting of all include and import modules (#31938)

* Unifying wording and formatting of all include and import modules

* Changes based on comments from dharmabumstead

* Removed instances of the term ‘Ansible Engine’

* Removed instances of term ‘Ansible Engine’

* Updated term

* Updated wording

* Updated wording

* Removed the term ‘Ansible Engine’

7 files changed, 169 insertions, 154 deletions

diff --git a/lib/ansible/modules/utilities/logic/_include.py b/lib/ansible/modules/utilities/logic/_include.py
index e232b28bd6..9afc17ad98 100644
--- a/lib/ansible/modules/utilities/logic/_include.py
+++ b/lib/ansible/modules/utilities/logic/_include.py
@@ -7,71 +7,74 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-ANSIBLE_METADATA = {'metadata_version': '1.1',
-                    'status': ['deprecated'],
-                    'supported_by': 'core'}
+ANSIBLE_METADATA = {
+    'metadata_version': '1.1',
+    'status': ['deprecated'],
+    'supported_by': 'core'
+}
 
 
 DOCUMENTATION = '''
 ---
-author:
-    - "Ansible Core Team (@ansible)"
+author: Ansible Core Team (@ansible)
 module: include
-short_description: include a play or task list.
+short_description: Include a play or task list
 deprecated:
-    The include action was too confusing, dealing with both plays and tasks, being both dynamic and static.  This module will be removed in version 2.8.
-    As alternatives use include_tasks, import_playbook, import_tasks.
+  The include action was too confusing, dealing with both plays and tasks, being both dynamic and static. This module
+  will be removed in version 2.8. As alternatives use M(include_tasks), M(import_playbook), M(import_tasks).
 description:
-     - Includes a file with a list of plays or tasks to be executed in the current playbook.
-     - Files with a list of plays can only be included at the top level, lists of tasks can only be included where tasks normally run (in play).
-     - Before 2.0 all includes were 'static', executed at play compile time.
-     - Static includes are not subject to most directives, for example, loops or conditionals, they are applied instead to each inherited task.
-     - Since 2.0 task includes are dynamic and behave more like real tasks.  This means they can be looped, skipped and use variables from any source.
-       Ansible tries to auto detect this, use the `static` directive (new in 2.1) to bypass autodetection.
-     - This module is also supported for Windows targets.
+  - Includes a file with a list of plays or tasks to be executed in the current playbook.
+  - Files with a list of plays can only be included at the top level. Lists of tasks can only be included where tasks
+    normally run (in play).
+  - Before Ansible version 2.0, all includes were 'static' and were executed when the play was compiled.
+  - Static includes are not subject to most directives. For example, loops or conditionals are applied instead to each
+    inherited task.
+  - Since Ansible 2.0, task includes are dynamic and behave more like real tasks. This means they can be looped,
+    skipped and use variables from any source. Ansible tries to auto detect this, but you can use the `static`
+    directive (which was added in Ansible 2.1) to bypass autodetection.
+  - This module is also supported for Windows targets.
 version_added: "0.6"
 options:
   free-form:
     description:
-        - This module allows you to specify the name of the file directly w/o any other options.
+      - This module allows you to specify the name of the file directly without any other options.
 notes:
-    - This is really not a module, though it appears as such, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a
-      module can.
-    - This module is also supported for Windows targets.
+  - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
+  - This module is also supported for Windows targets.
 '''
 
 EXAMPLES = """
-# include a play after another play
 - hosts: localhost
   tasks:
     - debug:
-        msg: "play1"
+        msg: play1
 
-- include: otherplays.yml
+- name: Include a play after another play
+  include: otherplays.yaml
 
 
-# include task list in play
 - hosts: all
   tasks:
     - debug:
         msg: task1
 
-    - include: stuff.yml
+    - name: Include task list in play
+      include: stuff.yaml
 
     - debug:
         msg: task10
 
-# dyanmic include task list in play
 - hosts: all
   tasks:
     - debug:
         msg: task1
 
-    - include: "{{ hostvar }}.yml"
+    - name: Include task list in play only if the condition is true
+      include: "{{ hostvar }}.yaml"
       static: no
       when: hostvar is defined
 """
 
 RETURN = """
-# this module does not return anything except plays or tasks to execute
+# This module does not return anything except plays or tasks to execute.
 """
diff --git a/lib/ansible/modules/utilities/logic/import_playbook.py b/lib/ansible/modules/utilities/logic/import_playbook.py
index b3e0b93245..4609fbab21 100644
--- a/lib/ansible/modules/utilities/logic/import_playbook.py
+++ b/lib/ansible/modules/utilities/logic/import_playbook.py
@@ -7,37 +7,38 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-ANSIBLE_METADATA = {'metadata_version': '1.1',
-                    'status': ['preview'],
-                    'supported_by': 'core'}
+ANSIBLE_METADATA = {
+    'metadata_version': '1.1',
+    'status': ['preview'],
+    'supported_by': 'core'
+}
 
 
 DOCUMENTATION = '''
 ---
-author:
-    - "Ansible Core Team (@ansible)"
+author: Ansible Core Team (@ansible)
 module: import_playbook
-short_description: import a playbook.
+short_description: Import a playbook
 description:
-     - Includes a file with a list of plays to be executed.
-     - Files with a list of plays can only be included at the top level, you cannot use this action inside a Play.
+  - Includes a file with a list of plays to be executed.
+  - Files with a list of plays can only be included at the top level. You cannot use this action inside a play.
 version_added: "2.4"
 options:
   free-form:
     description:
-        - This action allows you to specify the name of the file directly w/o any other options.
+      - The name of the imported playbook is specified directly without any other option.
 notes:
-    - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can.
+  - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
 '''
 
 EXAMPLES = """
-- name: include a play after another play
-  hosts: localhost
+- hosts: localhost
   tasks:
     - debug:
-        msg: "play1"
+        msg: play1
 
-- import_playbook: otherplays.yml
+- name: Include a play after another play
+  import_playbook: otherplays.yaml
 
 
 - name: This DOES NOT WORK
@@ -46,10 +47,10 @@ EXAMPLES = """
     - debug:
         msg: task1
 
-    - name: This failes because I'm inside a play already
-      import_playbook: stuff.yml
+    - name: This fails because I'm inside a play already
+      import_playbook: stuff.yaml
 """
 
 RETURN = """
-# this module does not return anything except plays to execute
+# This module does not return anything except plays to execute.
 """
diff --git a/lib/ansible/modules/utilities/logic/import_role.py b/lib/ansible/modules/utilities/logic/import_role.py
index 36df8a1e90..b123f4416b 100644
--- a/lib/ansible/modules/utilities/logic/import_role.py
+++ b/lib/ansible/modules/utilities/logic/import_role.py
@@ -7,21 +7,23 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-ANSIBLE_METADATA = {'metadata_version': '1.1',
-                    'status': ['preview'],
-                    'supported_by': 'core'}
+ANSIBLE_METADATA = {
+    'metadata_version': '1.1',
+    'status': ['preview'],
+    'supported_by': 'core'
+}
 
 
 DOCUMENTATION = '''
 ---
-author:
-    - "Ansible Core Team (@ansible)"
+author: Ansible Core Team (@ansible)
 module: import_role
 short_description: Import a role into a play
 description:
-     - Mostly like the `roles:` keyword this action loads a role, but it allows you to control when the tasks run in between other playbook tasks.
-     - Most keywords, loops and conditionals will not be applied to this action, but to the imported tasks instead.
-       If you want the opposite behaviour, use M(include_role) instead.
+  - Much like the `roles:` keyword, this task loads a role, but it allows you to control it when the role tasks run in
+    between other tasks of the play.
+  - Most keywords, loops and conditionals will only be applied to the imported tasks, not to this statement itself. If
+    you want the opposite behaviour, use M(include_role) instead.
 version_added: "2.4"
 options:
   name:
@@ -30,19 +32,19 @@ options:
     required: True
   tasks_from:
     description:
-      - "File to load from a Role's tasks/ directory."
+      - File to load from a role's C(tasks/) directory.
     required: False
-    default: 'main'
+    default: main
   vars_from:
     description:
-      - "File to load from a Role's vars/ directory."
+      - File to load from a role's C(vars/) directory.
     required: False
-    default: 'main'
+    default: main
   defaults_from:
     description:
-      - "File to load from a Role's defaults/ directory."
+      - File to load from a role's C(defaults/) directory.
     required: False
-    default: 'main'
+    default: main
   allow_duplicates:
     description:
       - Overrides the role's metadata setting to allow using a role more than once with the same parameters.
@@ -50,10 +52,11 @@ options:
     default: True
   private:
     description:
-      - If True the variables from defaults/ and vars/ in a role will not be made available to the rest of the play.
+      - If C(True) the variables from C(defaults/) and C(vars/) in a role will not be made available to the rest of the
+        play.
     default: None
 notes:
-    - Handlers are made available to the whole play.
+  - Handlers are made available to the whole play.
 '''
 
 EXAMPLES = """
@@ -62,7 +65,7 @@ EXAMPLES = """
     - import_role:
        name: myrole
 
-    - name: Run tasks/other.yml instead of 'main'
+    - name: Run tasks/other.yaml instead of 'main'
       import_role:
         name: myrole
         tasks_from: other
@@ -71,7 +74,7 @@ EXAMPLES = """
       import_role:
         name: myrole
       vars:
-        rolevar1: 'value from task'
+        rolevar1: value from task
 
     - name: Apply loop to each task in role
       import_role:
@@ -89,5 +92,5 @@ EXAMPLES = """
 """
 
 RETURN = """
-# this module does not return anything except tasks to execute
+# This module does not return anything except tasks to execute.
 """
diff --git a/lib/ansible/modules/utilities/logic/import_tasks.py b/lib/ansible/modules/utilities/logic/import_tasks.py
index 25aa51fffb..d107c5e02e 100644
--- a/lib/ansible/modules/utilities/logic/import_tasks.py
+++ b/lib/ansible/modules/utilities/logic/import_tasks.py
@@ -7,52 +7,53 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-ANSIBLE_METADATA = {'metadata_version': '1.1',
-                    'status': ['preview'],
-                    'supported_by': 'core'}
+ANSIBLE_METADATA = {
+    'metadata_version': '1.1',
+    'status': ['preview'],
+    'supported_by': 'core'
+}
 
 
 DOCUMENTATION = '''
 ---
-author:
-    - "Ansible Core Team (@ansible)"
+author: Ansible Core Team (@ansible)
 module: import_tasks
-short_description: import a task list.
+short_description: Import a task list
 description:
-     - Imports a list of tasks to be added to the current playbook for subsequent execution.
+  - Imports a list of tasks to be added to the current playbook for subsequent execution.
 version_added: "2.4"
 options:
   free-form:
     description:
-        - This action allows you to specify the name of the file directly w/o any other options.
-        - Any loops, conditionals and most other keywords will be applied to the included tasks, not to this statement itself.
-        - If you need any of those to apply to this action, use M(include_tasks) instead.
+      - The name of the imported file is specified directly without any other option.
+      - Most keywords, including loops and conditionals, only applied to the imported tasks, not to this statement
+        itself. If you need any of those to apply, use M(include_tasks) instead.
 notes:
-    - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can.
+  - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
 '''
 
 EXAMPLES = """
-# include task list in play
 - hosts: all
   tasks:
     - debug:
         msg: task1
 
-    - import_tasks: stuff.yml
+    - name: Include task list in play
+      import_tasks: stuff.yaml
 
     - debug:
         msg: task10
 
-# apply conditional to all imported tasks
-- hosts: all
+  hosts: all
   tasks:
     - debug:
         msg: task1
 
-    - import_tasks: stuff.yml
+    - name: Apply conditional to all imported tasks
+      import_tasks: stuff.yaml
       when: hostvar is defined
 """
 
 RETURN = """
-# this module does not return anything except tasks to execute
+# This module does not return anything except tasks to execute.
 """
diff --git a/lib/ansible/modules/utilities/logic/include_role.py b/lib/ansible/modules/utilities/logic/include_role.py
index 0ff592ac3c..862d877336 100644
--- a/lib/ansible/modules/utilities/logic/include_role.py
+++ b/lib/ansible/modules/utilities/logic/include_role.py
@@ -7,20 +7,23 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-ANSIBLE_METADATA = {'metadata_version': '1.1',
-                    'status': ['preview'],
-                    'supported_by': 'core'}
+ANSIBLE_METADATA = {
+    'metadata_version': '1.1',
+    'status': ['preview'],
+    'supported_by': 'core'
+}
 
 
 DOCUMENTATION = '''
 ---
-author:
-    - "Ansible Core Team (@ansible)"
+author: Ansible Core Team (@ansible)
 module: include_role
 short_description: Load and execute a role
 description:
-     - Loads and executes a role as a task, this frees roles from the `role:` directive and allows them to be treated more as tasks.
-     - This module is also supported for Windows targets.
+  - Loads and executes a role as a task dynamically. This frees roles from the `roles:` directive and allows them to be
+    treated more as tasks.
+  - Unlike M(import_role), most keywords, including loops and conditionals, apply to this statement.
+  - This module is also supported for Windows targets.
 version_added: "2.2"
 options:
   name:
@@ -29,19 +32,19 @@ options:
     required: True
   tasks_from:
     description:
-      - "File to load from a Role's tasks/ directory."
+      - File to load from a role's C(tasks/) directory.
     required: False
-    default: 'main'
+    default: main
   vars_from:
     description:
-      - "File to load from a Role's vars/ directory."
+      - File to load from a role's C(vars/) directory.
     required: False
-    default: 'main'
+    default: main
   defaults_from:
     description:
-      - "File to load from a Role's defaults/ directory."
+      - File to load from a role's C(defaults/) directory.
     required: False
-    default: 'main'
+    default: main
   allow_duplicates:
     description:
       - Overrides the role's metadata setting to allow using a role more than once with the same parameters.
@@ -49,21 +52,22 @@ options:
     default: True
   private:
     description:
-      - If True the variables from defaults/ and vars/ in a role will not be made available to the rest of the play.
+      - If C(True) the variables from C(defaults/) and C(vars/) in a role will not be made available to the rest of the
+        play.
     default: None
 notes:
-    - Handlers are made available to the whole play.
-    - Before 2.4, as with C(include), this task could be static or dynamic, If static it implied that it won't need templating nor loops nor conditionals
-      and will show included tasks in the --list options.
-      Ansible would try to autodetect what is needed, but you can set `static` to `yes` or `no` at task level to control this.
-    - After 2.4, you can use M(import_role) for 'static' behaviour and this action for 'dynamic' one.
+  - Handlers are made available to the whole play.
+  - Before Ansible 2.4, as with C(include), this task could be static or dynamic, If static, it implied that it won't
+    need templating, loops or conditionals and will show included tasks in the `--list` options. Ansible would try to
+    autodetect what is needed, but you can set `static` to `yes` or `no` at task level to control this.
+  - After Ansible 2.4, you can use M(import_role) for 'static' behaviour and this action for 'dynamic' one.
 '''
 
 EXAMPLES = """
 - include_role:
     name: myrole
 
-- name: Run tasks/other.yml instead of 'main'
+- name: Run tasks/other.yaml instead of 'main'
   include_role:
     name: myrole
     tasks_from: other
@@ -72,7 +76,7 @@ EXAMPLES = """
   include_role:
     name: myrole
   vars:
-    rolevar1: 'value from task'
+    rolevar1: value from task
 
 - name: Use role in loop
   include_role:
@@ -83,12 +87,12 @@ EXAMPLES = """
   loop_control:
     loop_var: roleinputvar
 
-- name: conditional role
+- name: Conditional role
   include_role:
     name: myrole
   when: not idontwanttorun
 """
 
 RETURN = """
-# this module does not return anything except tasks to execute
+# This module does not return anything except tasks to execute.
 """
diff --git a/lib/ansible/modules/utilities/logic/include_tasks.py b/lib/ansible/modules/utilities/logic/include_tasks.py
index 2eaa9bdade..67a8681eb4 100644
--- a/lib/ansible/modules/utilities/logic/include_tasks.py
+++ b/lib/ansible/modules/utilities/logic/include_tasks.py
@@ -7,51 +7,52 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-ANSIBLE_METADATA = {'metadata_version': '1.1',
-                    'status': ['preview'],
-                    'supported_by': 'core'}
+ANSIBLE_METADATA = {
+    'metadata_version': '1.1',
+    'status': ['preview'],
+    'supported_by': 'core'
+}
 
 
 DOCUMENTATION = '''
 ---
-author:
-    - "Ansible Core Team (@ansible)"
+author: Ansible Core Team (@ansible)
 module: include_tasks
-short_description: dynamically include a task list.
+short_description: Dynamically include a task list
 description:
-     - Includes a file with a list of tasks to be executed in the current playbook.
+  - Includes a file with a list of tasks to be executed in the current playbook.
 version_added: "2.4"
 options:
   free-form:
     description:
-      - This action allows you to specify the name of the file directly w/o any other options.
-      - Unlike M(import_tasks) this action will be affected by most keywords, including loops and conditionals.
+      - The name of the imported file is specified directly without any other option.
+      - Unlike M(import_tasks), most keywords, including loops and conditionals, apply to this statement.
 notes:
-  - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can.
+  - This is a core feature of the Ansible, rather than a module, and cannot be overridden like a module.
 '''
 
 EXAMPLES = """
-# include task list in play
 - hosts: all
   tasks:
     - debug:
         msg: task1
 
-    - include_tasks: stuff.yml
+    - name: Include task list in play
+      include_tasks: stuff.yaml
 
     - debug:
         msg: task10
 
-# dyanmic include task list in play
 - hosts: all
   tasks:
     - debug:
         msg: task1
 
-    - include_tasks: "{{ hostvar }}.yml"
+    - name: Include task list in play only if the condition is true
+      include_tasks: "{{ hostvar }}.yaml"
       when: hostvar is defined
 """
 
 RETURN = """
-# this module does not return anything except tasks to execute
+# This module does not return anything except tasks to execute.
 """
diff --git a/lib/ansible/modules/utilities/logic/include_vars.py b/lib/ansible/modules/utilities/logic/include_vars.py
index e82e76e2b6..921ca1e8e5 100644
--- a/lib/ansible/modules/utilities/logic/include_vars.py
+++ b/lib/ansible/modules/utilities/logic/include_vars.py
@@ -5,27 +5,29 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-ANSIBLE_METADATA = {'metadata_version': '1.1',
-                    'status': ['stableinterface'],
-                    'supported_by': 'core'}
+ANSIBLE_METADATA = {
+    'metadata_version': '1.1',
+    'status': ['stableinterface'],
+    'supported_by': 'core'
+}
 
 
 DOCUMENTATION = '''
 ---
-author: "Allen Sanabria (@linuxdynasty)"
+author: Allen Sanabria (@linuxdynasty)
 module: include_vars
-short_description: Load variables from files, dynamically within a task.
+short_description: Load variables from files, dynamically within a task
 description:
-    - Loads variables from a YAML/JSON files dynamically from within a file or from a directory recursively during task runtime. If loading a directory,
-      the files are sorted alphabetically before being loaded.
-    - This module is also supported for Windows targets.
+  - Loads variables from a YAML/JSON files dynamically from within a file or from a directory recursively during task
+    runtime. If loading a directory, the files are sorted alphabetically before being loaded.
+  - This module is also supported for Windows targets.
 version_added: "1.4"
 options:
   file:
     version_added: "2.2"
     description:
-       - The file name from which variables should be loaded.
-       - If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook.
+      - The file name from which variables should be loaded.
+      - If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook.
   dir:
     version_added: "2.2"
     description:
@@ -35,13 +37,13 @@ options:
   name:
     version_added: "2.2"
     description:
-        - The name of a variable into which assign the included vars, if omitted (null) they will be made top level vars.
+      - The name of a variable into which assign the included vars. If omitted (null) they will be made top level vars.
     default: null
   depth:
     version_added: "2.2"
     description:
-      - When using C(dir), this module will, by default, recursively go through each sub directory and load up the variables.
-        By explicitly setting the depth, this module will only go as deep as the depth.
+      - When using C(dir), this module will, by default, recursively go through each sub directory and load up the
+        variables. By explicitly setting the depth, this module will only go as deep as the depth.
     default: 0
   files_matching:
     version_added: "2.2"
@@ -57,65 +59,65 @@ options:
     version_added: "2.3"
     description:
       - List of file extensions to read when using C(dir).
-    default: ['yaml', 'yml', 'json']
+    default: [yaml, yml, json]
     required: False
   free-form:
     description:
-        - This module allows you to specify the 'file' option directly w/o any other options.
-          There is no 'free-form' option, this is just an indicator, see example below.
+      - This module allows you to specify the 'file' option directly without any other options.
+        There is no 'free-form' option, this is just an indicator, see example below.
 notes:
-    - This module is also supported for Windows targets.
+  - This module is also supported for Windows targets.
 '''
 
 EXAMPLES = """
-- name: Include vars of stuff.yml into the 'stuff' variable (2.2).
+- name: Include vars of stuff.yaml into the 'stuff' variable (2.2).
   include_vars:
-    file: stuff.yml
+    file: stuff.yaml
     name: stuff
 
 - name: Conditionally decide to load in variables into 'plans' when x is 0, otherwise do not. (2.2)
   include_vars:
-    file: contingency_plan.yml
+    file: contingency_plan.yaml
     name: plans
   when: x == 0
 
 - name: Load a variable file based on the OS type, or a default if not found. Using free-form to specify the file.
   include_vars: "{{ item }}"
   with_first_found:
-    - "{{ ansible_distribution }}.yml"
-    - "{{ ansible_os_family }}.yml"
-    - "default.yml"
+    - "{{ ansible_distribution }}.yaml"
+    - "{{ ansible_os_family }}.yaml"
+    - default.yaml
 
-- name: bare include (free-form)
-  include_vars: myvars.yml
+- name: Bare include (free-form)
+  include_vars: myvars.yaml
 
 - name: Include all .json and .jsn files in vars/all and all nested directories (2.3)
   include_vars:
-    dir: 'vars/all'
+    dir: vars/all
     extensions:
         - json
         - jsn
 
 - name: Include all default extension files in vars/all and all nested directories and save the output in test. (2.2)
   include_vars:
-    dir: 'vars/all'
+    dir: vars/all
     name: test
 
 - name: Include default extension files in vars/services (2.2)
   include_vars:
-    dir: 'vars/services'
+    dir: vars/services
     depth: 1
 
-- name: Include only files matching bastion.yml (2.2)
+- name: Include only files matching bastion.yaml (2.2)
   include_vars:
-    dir: 'vars'
-    files_matching: 'bastion.yml'
+    dir: vars
+    files_matching: bastion.yaml
 
-- name: Include all .yml files except bastion.yml (2.3)
+- name: Include all .yaml files except bastion.yaml (2.3)
   include_vars:
-    dir: 'vars'
-    ignore_files: 'bastion.yml'
-    extensions: ['yml']
+    dir: vars
+    ignore_files: bastion.yaml
+    extensions: [yaml]
 """
 
 RETURN = '''
@@ -128,6 +130,6 @@ ansible_included_var_files:
   description: A list of files that were successfully included
   returned: success
   type: list
-  sample: [ '/path/to/file.yml', '/path/to/file.json' ]
+  sample: [ '/path/to/file.yaml', '/path/to/file.json' ]
   version_added: 2.4
 '''