From a3489408a5e1bdbcd90996ec6f7a31c1c4490b31 Mon Sep 17 00:00:00 2001
From: Brian Coca <brian.coca+git@gmail.com>
Date: Fri, 26 Feb 2016 16:18:55 -0500
Subject: [PATCH] fixes to playbooks_directives generation

order is now predictable
now correctly substitutes loop for with_
adds local_action to action
---
 hacking/dump_playbook_attributes.py           | 25 ++++++++++++++++---
 hacking/templates/playbooks_directives.rst.j2 |  9 +++----
 2 files changed, 25 insertions(+), 9 deletions(-)

diff --git a/hacking/dump_playbook_attributes.py b/hacking/dump_playbook_attributes.py
index 3fa2b410846..89f5273f3c3 100755
--- a/hacking/dump_playbook_attributes.py
+++ b/hacking/dump_playbook_attributes.py
@@ -10,9 +10,8 @@ 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
+clist = []
+class_list = [ Play, Role, Block, Task ]
 
 p = optparse.OptionParser(
     version='%prog 1.0',
@@ -24,10 +23,28 @@ p.add_option("-o", "--output-dir", action="store", dest="output_dir", default='/
 
 (options, args) = p.parse_args()
 
+for aclass in class_list
+    aobj = aclass()
+    name = type(aobj).__name__
+
+    # build ordered list to loop over and dict with attributes
+    clist.append(name)
+    oblist[name] = aobj.__dict__['_attributes']
+
+    # loop is really with_ for users
+    if 'loop' in oblist[name]:
+        oblist[name]['with_<lookup_plugin>'] = True
+        del oblist[name]['loop']
+        del oblist[name]['loop_args']
+
+    # local_action is implicit with action
+    if 'action' in oblist[name]:
+        oblist[name]['local_action'] = True
+
 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 }
+tempvars = { 'oblist': oblist, 'clist': clist }
 
 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
index 6f0528cefed..e54d0d455d4 100644
--- a/hacking/templates/playbooks_directives.rst.j2
+++ b/hacking/templates/playbooks_directives.rst.j2
@@ -1,21 +1,20 @@
 Directives Glossary
 ===================
 
-Here we list the common playbook objects and the possible directives that can be used with them.
+Here we list the common playbook objects and the their directives.
 Note that not all directives affect the object itself and might just be there to be inherited by other contained objects.
+Aliases for the directives are not reflected here, nor are mutable ones, for example `action` in task can be substituted by the name of any module plugin.
 
 .. contents::
    :local:
    :depth: 1
 
-{% for name in oblist %}
+{% for name in clist %}
 
 {{ name }}
 {{ '-' * name|length }}
-{% for attribute in oblist[name].__dict__['_attributes']|sort %}
-{% if attribute not in ['loop', 'loop_args'] %}
+{% for attribute in oblist[name]|sort %}
   * {{ attribute }}
-{% endif %}
 {% endfor %}
 
 {% endfor %}