Cleaning up use of include: in docs (#30466)

* Cleaning up use of include: in docs

Switching to import_*/include_* instead.

* Update playbooks_best_practices.rst

* Fix rst syntax

docs/docsite/rst/galaxy.rst

@@ -152,7 +152,7 @@ Content of the *requirements.yml* file:
     # from galaxy
     - src: yatesr.timezone
 
-    - include: <path_to_requirements>/webserver.yml
+    - import_tasks: <path_to_requirements>/webserver.yml
 
 
 Content of the *webserver.yml* file:

docs/docsite/rst/playbooks_async.rst

@@ -94,7 +94,7 @@ of tasks running concurrently, you can do it this way::
           - 4
           - 5
         durations: "{{ item }}"
-      include: execute_batch.yml
+      include_tasks: execute_batch.yml
       with_items:
         - "{{ sleep_durations | batch(2) | list }}"
 

docs/docsite/rst/playbooks_best_practices.rst

@@ -216,15 +216,15 @@ variables from the file "group_vars/ec2_tag_class_webserver" automatically.
 Top Level Playbooks Are Separated By Role
 `````````````````````````````````````````
 
-In site.yml, we include a playbook that defines our entire infrastructure.  Note this is SUPER short, because it's just including
+In site.yml, we import a playbook that defines our entire infrastructure.  This is a very short example, because it's just importing
-some other playbooks.  Remember, playbooks are nothing more than lists of plays::
+some other playbooks::
 
     ---
     # file: site.yml
-    - include: webservers.yml
+    - import_plays: webservers.yml
-    - include: dbservers.yml
+    - import_plays: dbservers.yml
 
-In a file like webservers.yml (also at the top level), we simply map the configuration of the webservers group to the roles performed by the webservers group.  Also notice this is incredibly short.  For example::
+In a file like webservers.yml (also at the top level), we map the configuration of the webservers group to the roles performed by the webservers group::
 
     ---
     # file: webservers.yml

docs/docsite/rst/playbooks_conditionals.rst

@@ -154,13 +154,13 @@ there will be accessible to future tasks::
 
 .. _when_roles_and_includes:
 
-Applying 'when' to roles and includes
+Applying 'when' to roles, imports, and includes
-`````````````````````````````````````
+```````````````````````````````````````````````
 
 Note that if you have several tasks that all share the same conditional statement, you can affix the conditional
 to a task include statement as below.  All the tasks get evaluated, but the conditional is applied to each and every task::
 
-    - include: tasks/sometasks.yml
+    - import_tasks: tasks/sometasks.yml
       when: "'reticulating splines' in output"
 
 .. note:: In versions prior to 2.0 this worked with task includes but not playbook includes.  2.0 allows it to work with both.
@@ -174,6 +174,24 @@ Or with a role::
 You will note a lot of 'skipped' output by default in Ansible when using this approach on systems that don't match the criteria.
 Read up on the 'group_by' module in the :doc:`modules` docs for a more streamlined way to accomplish the same thing.
 
+When used with `include_*` tasks instead of imports, the conditional is applied _only_ to the include task itself and not any other
+tasks within the included file(s). A common situation where this distinction is important is as follows::
+
+    # include a file to define a variable when it is not already defined
+
+    # main.yml
+    - include_tasks: other_tasks.yml
+      when: x is not defined
+
+    # other_tasks.yml
+    - set_fact:
+        x: foo
+    - debug:
+        var: x
+
+In the above example, if ``import_tasks`` had been used instead both included tasks would have also been skipped. With ``include_tasks``
+instead, the tasks are executed as expected because the conditional is not applied to them.
+
 .. _conditional_imports:
 
 Conditional Imports

docs/docsite/rst/playbooks_intro.rst

@@ -359,7 +359,7 @@ a variable called ``vhost`` in the ``vars`` section, you could do this::
 Those same variables are usable in templates, which we'll get to later.
 
 Now in a very basic playbook all the tasks will be listed directly in that play, though it will usually
-make more sense to break up tasks using the ``include:`` directive.  We'll show that a bit later.
+make more sense to break up tasks as described in :doc:`playbooks_reuse`.
 
 .. _action_shorthand:
 

docs/docsite/rst/playbooks_loops.rst

@@ -743,7 +743,7 @@ Ansible by default sets the loop variable `item` for each loop, which causes the
 As of Ansible 2.1, the `loop_control` option can be used to specify the name of the variable to be used for the loop::
 
     # main.yml
-    - include: inner.yml
+    - include_tasks: inner.yml
       with_items:
         - 1
         - 2
@@ -807,7 +807,7 @@ Because `loop_control` is not available in Ansible 2.0, when using an include wi
 for `item`::
 
     # main.yml
-    - include: inner.yml
+    - include_tasks: inner.yml
       with_items:
         - 1
         - 2

docs/docsite/rst/playbooks_tags.rst

@@ -80,9 +80,14 @@ You may also apply tags to roles::
     roles:
       - { role: webserver, port: 5000, tags: [ 'web', 'foo' ] }
 
-And include statements::
+And import/include statements::
 
-    - include: foo.yml
+    - import_tasks: foo.yml
+      tags: [web,foo]
+
+or::
+
+    - include_tasks: foo.yml
       tags: [web,foo]
 
 All of these apply the specified tags to EACH task inside the play, included

docs/docsite/rst/porting_guide_2.0.rst

@@ -138,12 +138,12 @@ While all items listed here will show a deprecation warning message, they still
 
 * Specifying variables at the top level of a task include statement is no longer supported. For example::
 
-    - include: foo.yml
+    - include_tasks: foo.yml
         a: 1
 
 Should now be::
 
-    - include: foo.yml
+    - include_tasks: foo.yml
       vars:
         a: 1
 
@@ -152,11 +152,11 @@ Should now be::
 * Tags (or any directive) should no longer be specified with other parameters in a task include. Instead, they should be specified as an option on the task.
   For example::
 
-    - include: foo.yml tags=a,b,c
+    - include_tasks: foo.yml tags=a,b,c
 
   Should be::
 
-    - include: foo.yml
+    - include_tasks: foo.yml
       tags: [a, b, c]
 
 * The first_available_file option on tasks has been deprecated. Users should use the with_first_found option or lookup (‘first_found’, …) plugin.