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

(cherry picked from commit 366a9d861f68baee0991f450289d060d382a980b)

8 files changed, 42 insertions, 19 deletions

diff --git a/docs/docsite/rst/galaxy.rst b/docs/docsite/rst/galaxy.rst
index a0028be2e9..728898caea 100644
--- a/docs/docsite/rst/galaxy.rst
+++ b/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:
diff --git a/docs/docsite/rst/playbooks_async.rst b/docs/docsite/rst/playbooks_async.rst
index 60fe8c4634..026c006e87 100644
--- a/docs/docsite/rst/playbooks_async.rst
+++ b/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 }}"
 
diff --git a/docs/docsite/rst/playbooks_best_practices.rst b/docs/docsite/rst/playbooks_best_practices.rst
index 3939e38c3a..aab4d114b1 100644
--- a/docs/docsite/rst/playbooks_best_practices.rst
+++ b/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
-some other playbooks.  Remember, playbooks are nothing more than lists of plays::
+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::
 
     ---
     # file: site.yml
-    - include: webservers.yml
-    - include: dbservers.yml
+    - import_plays: webservers.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
diff --git a/docs/docsite/rst/playbooks_conditionals.rst b/docs/docsite/rst/playbooks_conditionals.rst
index e4875d6cb9..f79c82c06e 100644
--- a/docs/docsite/rst/playbooks_conditionals.rst
+++ b/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
diff --git a/docs/docsite/rst/playbooks_intro.rst b/docs/docsite/rst/playbooks_intro.rst
index 20cf57bcc7..ee87316b06 100644
--- a/docs/docsite/rst/playbooks_intro.rst
+++ b/docs/docsite/rst/playbooks_intro.rst
@@ -345,7 +345,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:
 
diff --git a/docs/docsite/rst/playbooks_loops.rst b/docs/docsite/rst/playbooks_loops.rst
index 515630f5ec..44b3c2f3fc 100644
--- a/docs/docsite/rst/playbooks_loops.rst
+++ b/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
diff --git a/docs/docsite/rst/playbooks_tags.rst b/docs/docsite/rst/playbooks_tags.rst
index d8dac98409..0867eaa5bd 100644
--- a/docs/docsite/rst/playbooks_tags.rst
+++ b/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
diff --git a/docs/docsite/rst/porting_guide_2.0.rst b/docs/docsite/rst/porting_guide_2.0.rst
index 9919a4707c..c8774663b7 100644
--- a/docs/docsite/rst/porting_guide_2.0.rst
+++ b/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.