From 44c5b056cb4f6a36add355236203944f61f02185 Mon Sep 17 00:00:00 2001
From: Brian Coca <brian.coca+git@gmail.com>
Date: Fri, 30 Sep 2016 00:53:09 -0400
Subject: [PATCH] 1st draft of include docs

---
 utilities/logic/include.py | 59 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 utilities/logic/include.py

diff --git a/utilities/logic/include.py b/utilities/logic/include.py
new file mode 100644
index 00000000000..c251c501dd0
--- /dev/null
+++ b/utilities/logic/include.py
@@ -0,0 +1,59 @@
+#!/usr/bin/python
+# -*- mode: python -*-
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+DOCUMENTATION = '''
+---
+author:
+    - "Ansible Core Team (@ansible)"
+module: include
+short_description: include a play or task list.
+description:
+     - Loads 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 load time.
+     - 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.
+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.
+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.
+'''
+
+EXAMPLES = """
+# include a play after another play
+- hosts: localhost
+  tasks:
+    - debug: msg="play1"
+
+- include: otherplays.yml
+
+
+# include task list in play
+- hosts: all
+  tasks:
+    - debug: msg=task1
+    - include: stuff.yml
+    - debug: msg=task10
+
+# dyanmic include task list in play
+- hosts: all
+  tasks:
+    - debug: msg=task1
+    - include: {{hostvar}}.yml
+      static: no
+      when: hostvar is defined
+"""
+
+RETURN = """
+# this module does not return anything except plays or tasks to execute
+"""