Merge pull request #220 from lorin/include-playbook

Document including one playbook inside another

rst/playbooks.rst

@@ -331,6 +331,26 @@ of a play::
 
 You can mix in includes along with your regular non-included tasks and handlers.
 
+Includes can also be used to import one playbook file into another. This allows
+you to define a top-level playbook that is composed of other playbooks.
+
+For example::
+
+    - name: this is a play at the top level of a file
+      hosts: all
+      user: root
+      tasks:
+      - name: say hi
+        tags: foo
+        action: shell echo "hi..."
+
+    - include: load_balancers.yml
+    - include: webservers.yml
+    - include: dbservers.yml
+
+Note that you cannot do variable substitution when including one playbook
+inside another.
+
 .. note::
 
    You can not conditionally path the location to an include file,