Update include_role description (#56001)

* Update include_role description to discuss tasks: use

The previous description in this statement's description really threw me off, and is IMO ambiguous at best. '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.'

For reference, I spent a long time trying to make include_role, with a loop, work under a roles: section. It doesn't work, but this documentation and its use of the roles: keyword in the opening, and the phrase '"more" as a task' muddies the waters.

+label: docsite_pr
This commit is contained in:
Alicia Cozine 2019-05-06 15:17:50 -05:00 committed by Sandra McCann
parent dc711c3018
commit 8cb76408d3

View file

@ -19,16 +19,17 @@ author: Ansible Core Team (@ansible)
module: include_role module: include_role
short_description: Load and execute a role short_description: Load and execute a role
description: description:
- Loads and executes a role as a task dynamically. - Dynamically loads and executes a specified role as a task.
- This frees roles from the C(roles:) directive and allows them to be treated more as tasks. - May be used only where Ansible tasks are allowed - inside C(pre_tasks), C(tasks), or C(post_tasks) playbook objects, or as a task inside a role.
- Unlike M(import_role), most keywords, including loop, with_items, and conditionals, apply to this statement. - Task-level keywords, loops, and conditionals apply only to the C(include_role) statement itself.
- The do until loop is not supported on M(include_role). - To apply keywords to the tasks within the role, pass them using the C(apply) option or use M(import_role) instead.
- Ignores some keywords, like C(until) and C(retries).
- This module is also supported for Windows targets. - This module is also supported for Windows targets.
version_added: "2.2" version_added: "2.2"
options: options:
apply: apply:
description: description:
- Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to the tasks within the include. - Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to all tasks within the included role.
version_added: '2.7' version_added: '2.7'
name: name:
description: description: