Doc directives (#22524)

* draft docs for directives

* updated to document directives

docs/docsite/Makefile

@@ -40,7 +40,7 @@ clean:
 .PHONEY: docs clean
 
 directives: $(FORMATTER) ../../hacking/templates/rst.j2
-	PYTHONPATH=../../lib $(DUMPER) --template-dir=../../hacking/templates --output-dir=rst/
+	PYTHONPATH=../../lib $(DUMPER) --template-dir=../../hacking/templates --output-dir=rst/ -d ./directive_desc.yml
 
 modules: $(FORMATTER) ../../hacking/templates/rst.j2
 	PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../../hacking/templates --module-dir=../../lib/ansible/modules -o rst/

docs/docsite/directive_desc.yml

@@ -0,0 +1,23 @@
+become: Boolean that controls if privilege escalation is used or not on Task execution.
+become_flags: A string of flag(s) to pass to the privilege escalation program when ``become`` is True.
+become_method: Which method of privilege escalation to use. i.e. sudo/su/etc.
+become_user: User that you 'become' after using privilege escalation, the remote/login user must have permissions to become this user.
+check_mode: A boolean that controls if a task is executed in 'check' mode
+connection: Allows you to change the connection plugin used for tasks to execute on the target.
+environment: A dictionary that gets converted into environment vars to be provided for the task upon execution.
+gather_facts: A boolean that controls if the play will automatically run the 'setup' task to gather facts for the hosts.
+hosts: A list of groups, hosts or host pattern that translates into a list of hosts that are the play's target.
+ignore_errors: Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
+name: It's a name, works mostly for documentation, in the case of tasks/handlers it can be an identifier.
+remote_user: User used to log into the target via the connection plugin. AKA login user.
+no_log: Boolean that controls information disclosure.
+run_once: Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
+when: Conditional expression, determines if an iteration of a task is run or not.
+strategy: Allows you to choose the connection plugin to use for the play.
+tags: Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
+vars: Dictionary/map of variables
+always_run: DEPRECATED, forces a task to run even in check mode, use check_mode directive instead.
+delegate_to: Host to execute task instead of the target (inventory_hostname), connection vars from the delegated host will also be used for the task.
+delegate_facts: Boolean that allows you to apply facts to delegated host instead of inventory_hostname.
+changed_when: Conditional expression that overrides the task's normal 'changed' status.
+failed_when: Conditional expression that overrides the task's normal 'failed' status.

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)

hacking/templates/playbooks_directives.rst.j2

@@ -14,7 +14,7 @@ Aliases for the directives are not reflected here, nor are mutable ones, for exa
 {{ name }}
 {{ '-' * name|length }}
 {% for attribute in oblist[name]|sort %}
-  * {{ attribute }}
+  - **{{ attribute }}:** {{ oblist[name][attribute] }}
 {% endfor %}
 
 {% endfor %}