From fbdcb22e36f6aeb01e10f972b8a4e7d691b1f908 Mon Sep 17 00:00:00 2001
From: Brian Coca <brian.coca+git@gmail.com>
Date: Thu, 25 Feb 2016 16:41:50 -0500
Subject: [PATCH] now generate list of playbook ojbect directives

TODO: needs links/info and conditionals added
---
 .gitignore                                    |  1 +
 docsite/Makefile                              |  6 +++-
 docsite/rst/playbooks_special_topics.rst      |  1 +
 hacking/dump_playbook_attributes.py           | 33 +++++++++++++++++++
 hacking/templates/playbooks_directives.rst.j2 | 19 +++++++++++
 5 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100755 hacking/dump_playbook_attributes.py
 create mode 100644 hacking/templates/playbooks_directives.rst.j2

diff --git a/.gitignore b/.gitignore
index 2392614453b..bbe61d075b9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,6 +31,7 @@ docs/man/man3/*
 *.sublime-workspace
 # docsite stuff...
 docsite/rst/modules_by_category.rst
+docsite/rst/playbooks_directives.rst
 docsite/rst/list_of_*.rst
 docsite/rst/*_module.rst
 docsite/*.html
diff --git a/docsite/Makefile b/docsite/Makefile
index 2b87827c597..f7f5e533271 100644
--- a/docsite/Makefile
+++ b/docsite/Makefile
@@ -1,10 +1,11 @@
 #!/usr/bin/make
 SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")
 FORMATTER=../hacking/module_formatter.py
+DUMPER=../hacking/dump_playbook_attributes.py
 
 all: clean docs
 
-docs: clean modules staticmin
+docs: clean directives modules staticmin
 	./build-site.py
 	-(cp *.ico htmlout/)
 	-(cp *.jpg htmlout/)
@@ -41,6 +42,9 @@ clean:
 
 .PHONEY: docs clean
 
+directives: $(FORMATTER) ../hacking/templates/rst.j2
+	PYTHONPATH=../lib $(DUMPER) --template-dir=../hacking/templates --output-dir=rst/
+
 modules: $(FORMATTER) ../hacking/templates/rst.j2
 	PYTHONPATH=../lib $(FORMATTER) -t rst --template-dir=../hacking/templates --module-dir=../lib/ansible/modules -o rst/
 
diff --git a/docsite/rst/playbooks_special_topics.rst b/docsite/rst/playbooks_special_topics.rst
index 943f2674eb0..6593d20a54a 100644
--- a/docsite/rst/playbooks_special_topics.rst
+++ b/docsite/rst/playbooks_special_topics.rst
@@ -20,3 +20,4 @@ and adopt these only if they seem relevant or useful to your environment.
    playbooks_tags
    playbooks_vault
    playbooks_startnstep
+   playbooks_directives
diff --git a/hacking/dump_playbook_attributes.py b/hacking/dump_playbook_attributes.py
new file mode 100755
index 00000000000..3fa2b410846
--- /dev/null
+++ b/hacking/dump_playbook_attributes.py
@@ -0,0 +1,33 @@
+#!/usr/bin/env python2
+
+import optparse
+from jinja2 import Environment, FileSystemLoader
+
+from ansible.playbook import  Play
+from ansible.playbook.block import  Block
+from ansible.playbook.role import  Role
+from ansible.playbook.task import  Task
+
+template_file = 'playbooks_directives.rst.j2'
+oblist = {}
+for aclass in Play, Block, Role, Task:
+    aobj = aclass()
+    oblist[type(aobj).__name__] = aobj
+
+p = optparse.OptionParser(
+    version='%prog 1.0',
+    usage='usage: %prog [options]',
+    description='Generate module documentation from metadata',
+)
+p.add_option("-T", "--template-dir", action="store", dest="template_dir", default="hacking/templates", help="directory containing Jinja2 templates")
+p.add_option("-o", "--output-dir", action="store", dest="output_dir", default='/tmp/', help="Output directory for rst files")
+
+(options, args) = p.parse_args()
+
+env = Environment(loader=FileSystemLoader(options.template_dir), trim_blocks=True,)
+template = env.get_template(template_file)
+outputname = options.output_dir + template_file.replace('.j2','')
+tempvars = { 'oblist': oblist }
+
+with open( outputname, 'w') as f:
+    f.write(template.render(tempvars))
diff --git a/hacking/templates/playbooks_directives.rst.j2 b/hacking/templates/playbooks_directives.rst.j2
new file mode 100644
index 00000000000..0dc9408e430
--- /dev/null
+++ b/hacking/templates/playbooks_directives.rst.j2
@@ -0,0 +1,19 @@
+Directives Glossary
+===================
+
+Here we list the common playbook objects and the possible directives that can be used with them.
+Note that not all directives affect the object itself and might just be there to be inherited by other contained objects.
+
+.. contents::
+   :local:
+   :depth: 1
+
+{% for name in oblist %}
+
+{{ name }}
+{{ '-' * name|length }}
+{% for attribute in oblist[name].__dict__['_attributes']|sort %}
+  * {{ attribute }}
+{% endfor %}
+
+{% endfor %}