From b606bcec040642ba9c8ba272c719ae8852d20fa1 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 15 Mar 2017 11:29:58 -0400 Subject: [PATCH] Doc directives (#22524) * draft docs for directives * updated to document directives --- docs/docsite/Makefile | 2 +- docs/docsite/directive_desc.yml | 23 +++++++++++++++++++ hacking/dump_playbook_attributes.py | 20 ++++++++++++++-- hacking/templates/playbooks_directives.rst.j2 | 2 +- 4 files changed, 43 insertions(+), 4 deletions(-) create mode 100644 docs/docsite/directive_desc.yml diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile index f534dc9c8b9..0288d8ffc8f 100644 --- a/docs/docsite/Makefile +++ b/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/ diff --git a/docs/docsite/directive_desc.yml b/docs/docsite/directive_desc.yml new file mode 100644 index 00000000000..d617214c8b5 --- /dev/null +++ b/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. diff --git a/hacking/dump_playbook_attributes.py b/hacking/dump_playbook_attributes.py index 204fe3fd325..8b4ea6b0491 100755 --- a/hacking/dump_playbook_attributes.py +++ b/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_'] = True + oblist[name]['with_'] = '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) diff --git a/hacking/templates/playbooks_directives.rst.j2 b/hacking/templates/playbooks_directives.rst.j2 index c01a179c347..f55bc2afc5b 100644 --- a/hacking/templates/playbooks_directives.rst.j2 +++ b/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 %}