Doc directives (#22524)

* draft docs for directives

* updated to document directives

hacking/dump_playbook_attributes.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python
 
 import optparse
+import yaml
+
 from jinja2 import Environment, FileSystemLoader
 
 from ansible.playbook import Play
@@ -20,6 +22,7 @@ p = optparse.OptionParser(
 )
 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")
+p.add_option("-d", "--docs-source", action="store", dest="docs", default=None, help="Source for attribute docs")
 
 (options, args) = p.parse_args()
 
@@ -27,17 +30,30 @@ for aclass in class_list:
     aobj = aclass()
     name = type(aobj).__name__
 
+    if options.docs:
+        with open(options.docs) as f:
+            docs = yaml.safe_load(f)
+    else:
+        docs = {}
+
     # build ordered list to loop over and dict with attributes
     clist.append(name)
     oblist[name] = dict((x, aobj.__dict__['_attributes'][x]) for x in aobj.__dict__['_attributes'] if 'private' not in x or not x.private)
 
+    # pick up docs if they exist
+    for a in oblist[name]:
+        if a in docs:
+            oblist[name][a] = docs[a]
+        else:
+            oblist[name][a] = ' UNDOCUMENTED!! '
+
     # loop is really with_ for users
     if name == 'Task':
-        oblist[name]['with_<lookup_plugin>'] = True
+        oblist[name]['with_<lookup_plugin>'] = 'with_ is how loops are defined, it can use any available lookup plugin to generate the item list'
 
     # local_action is implicit with action
     if 'action' in oblist[name]:
-        oblist[name]['local_action'] = True
+        oblist[name]['local_action'] = 'Same as action but also implies `delegate_to: localhost`'
 
 env = Environment(loader=FileSystemLoader(options.template_dir), trim_blocks=True,)
 template = env.get_template(template_file)