diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rwxr-xr-x | docs/bin/dump_keywords.py | 14 | ||||
| -rwxr-xr-x | docs/bin/plugin_formatter.py | 9 | ||||
| -rw-r--r-- | docs/docsite/keyword_desc.yml | 54 | ||||
| -rw-r--r-- | docs/templates/playbooks_keywords.rst.j2 | 20 |
5 files changed, 67 insertions, 32 deletions
diff --git a/.gitignore b/.gitignore index ac6520869c..3f43644cec 100644 --- a/.gitignore +++ b/.gitignore @@ -50,7 +50,7 @@ docs/docsite/rst/modules_by_category.rst docs/docsite/rst/network_maintained.rst docs/docsite/rst/plugins_by_category.rst docs/docsite/rst/partner_maintained.rst -docs/docsite/rst/playbook_keywords.rst +docs/docsite/rst/playbooks_keywords.rst docs/docsite/rst/playbooks_directives.rst docs/docsite/rst/plugins/*/*.rst # deb building stuff... diff --git a/docs/bin/dump_keywords.py b/docs/bin/dump_keywords.py index 38b46147ba..339901d5db 100755 --- a/docs/bin/dump_keywords.py +++ b/docs/bin/dump_keywords.py @@ -1,8 +1,11 @@ #!/usr/bin/env python import optparse -import yaml +import re +from distutils.version import LooseVersion +import jinja2 +import yaml from jinja2 import Environment, FileSystemLoader from ansible.playbook import Play @@ -18,7 +21,7 @@ class_list = [Play, Role, Block, Task] p = optparse.OptionParser( version='%prog 1.0', usage='usage: %prog [options]', - description='Generate module documentation from metadata', + description='Generate playbook keyword documentation from code and descriptions', ) p.add_option("-T", "--template-dir", action="store", dest="template_dir", default="../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") @@ -66,5 +69,10 @@ template = env.get_template(template_file) outputname = options.output_dir + template_file.replace('.j2', '') tempvars = {'oblist': oblist, 'clist': clist} +keyword_page = template.render(tempvars) +if LooseVersion(jinja2.__version__) < LooseVersion('2.10'): + # jinja2 < 2.10's indent filter indents blank lines. Cleanup + keyword_page = re.sub(' +\n', '\n', keyword_page) + with open(outputname, 'w') as f: - f.write(template.render(tempvars)) + f.write(keyword_page) diff --git a/docs/bin/plugin_formatter.py b/docs/bin/plugin_formatter.py index d50cd9806d..77545c996d 100755 --- a/docs/bin/plugin_formatter.py +++ b/docs/bin/plugin_formatter.py @@ -26,11 +26,13 @@ import datetime import glob import optparse import os -from pprint import PrettyPrinter import re import sys import warnings from collections import defaultdict +from distutils.version import LooseVersion +from pprint import PrettyPrinter + try: from html import escape as html_escape except ImportError: @@ -40,6 +42,7 @@ except ImportError: def html_escape(text, quote=True): return cgi.escape(text, quote) +import jinja2 import yaml from jinja2 import Environment, FileSystemLoader from six import iteritems, string_types @@ -444,6 +447,10 @@ def process_plugins(module_map, templates, outputname, output_dir, ansible_versi display.v('about to template %s' % module) display.vvvvv(pp.pformat(doc)) text = templates['plugin'].render(doc) + if LooseVersion(jinja2.__version__) < LooseVersion('2.10'): + # jinja2 < 2.10's indent filter indents blank lines. Cleanup + text = re.sub(' +\n', '\n', text) + write_data(text, output_dir, outputname, module) diff --git a/docs/docsite/keyword_desc.yml b/docs/docsite/keyword_desc.yml index b9f30b7b2e..583ffb2e69 100644 --- a/docs/docsite/keyword_desc.yml +++ b/docs/docsite/keyword_desc.yml @@ -1,52 +1,68 @@ -accelerate: DEPRECATED, set to True to use accelerate connection plugin. -accelerate_ipv6: "DEPRECATED, set to True to force accelerate plugin to use ipv6 for it's connection." -accelerate_port: DEPRECATED, set to override default port use for accelerate connection. +accelerate: "*DEPRECATED*, set to True to use accelerate connection plugin." +accelerate_ipv6: "*DEPRECATED*, set to True to force accelerate plugin to use ipv6 for its connection." +accelerate_port: "*DEPRECATED*, set to override default port use for accelerate connection." action: "The 'action' to execute for a task, it normally translates into a C(module) or action plugin." -args: DEPRECATED, A secondary way to add arguments into a task, it takes a dictionary in which keys map to options and values .. well you get it. +args: "*DEPRECATED*, A secondary way to add arguments into a task. Takes a dictionary in which keys map to options and values." always: List of tasks, in a block, that execute no matter if there is an error in the block or not. -always_run: DEPRECATED, forces a task to run even in check mode, use :term:`check_mode` directive instead. +always_run: "*DEPRECATED*, forces a task to run even in check mode. Use :term:`check_mode` directive instead." any_errors_fatal: Force any un-handled task errors on any host to propagate to all hosts and end the play. async: Run a task asyncronouslly if the C(action) supports this. become: Boolean that controls if privilege escalation is used or not on :term:`Task` execution. become_flags: A string of flag(s) to pass to the privilege escalation program when :term:`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." +become_method: Which method of privilege escalation to use (such as sudo or su). +become_user: "User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user." block: List of tasks in a block. changed_when: "Conditional expression that overrides the task's normal 'changed' status." -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. -delay: Number of seconds to delay between retries, this setting is only used in combination with :term:`until`. -delegate_facts: Boolean that allows you to apply facts to delegated host instead of inventory_hostname. -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. +check_mode: | + A boolean that controls if a task is executed in 'check' mode + + .. seealso:: :ref:`check_mode_dry` + +connection: | + Allows you to change the connection plugin used for tasks to execute on the target. + + .. seealso:: :ref:`using_connection` + +delay: Number of seconds to delay between retries. This setting is only used in combination with :term:`until`. +delegate_facts: Boolean that allows you to apply facts to a delegated host instead of inventory_hostname. +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. diff: "Toggle to make tasks return 'diff' information or not." environment: A dictionary that gets converted into environment vars to be provided for the task upon execution. fact_path: Set the fact path option for the fact gathering plugin controlled by :term:`gather_facts`. failed_when: "Conditional expression that overrides the task's normal 'failed' status." -force_handlers: Will force notified handler execution for hosts even if they failed during the play, it will not trigger if the play itself fails. +force_handlers: Will force notified handler execution for hosts even if they failed during the play. Will not trigger if the play itself fails. gather_facts: "A boolean that controls if the play will automatically run the 'setup' task to gather facts for the hosts." gather_subset: Allows you to pass subset options to the fact gathering plugin controlled by :term:`gather_facts`. gather_timeout: Allows you to set the timeout for the fact gathering plugin controlled by :term:`gather_facts`. -handlers: "A section with tasks that are treated as handlers, these won't get executed normally, only when notified. After each section of tasks is complete." +handlers: "A section with tasks that are treated as handlers, these won't get executed normally, only when notified after each section of tasks is complete." 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. loop: "Takes a list for the task to iterate over, saving each list element into the ``item`` variable (configurable via loop_control)" -loop_control: "Several keys here allow you to modify/set loop behaviour in a task see http://docs.ansible.com/ansible/latest/playbooks_loops.html#loop-control for details." +loop_control: | + Several keys here allow you to modify/set loop behaviour in a task. + + .. seealso:: :ref:`loop_control` + max_fail_percentage: can be used to abort the run after a given percentage of hosts in the current batch has failed. -name: "It's a name, works mostly for documentation, in the case of tasks/handlers it can be an identifier." +name: "Identifier. Can be used for documentation, in or tasks/handlers." no_log: Boolean that controls information disclosure. -notify: "list of handlers to notify when the task returns a 'changed=True' status." +notify: "List of handlers to notify when the task returns a 'changed=True' status." order: Controls the sorting of hosts as they are used for executing the play. Possible values are inventory (default), sorted, reverse_sorted, reverse_inventory and shuffle. poll: Sets the polling interval in seconds for async tasks (default 10s). port: Used to override the default port used in a connection. post_tasks: A list of tasks to execute after the :term:`tasks` section. pre_tasks: A list of tasks to execute before :term:`roles`. -remote_user: User used to log into the target via the connection plugin. AKA login user. +remote_user: User used to log into the target via the connection plugin. register: Name of variable that will contain task status and module return data. rescue: List of tasks in a :term:`block` that run if there is a task error in the main :term:`block` list. retries: "Number of retries before giving up in a :term:`until` loop. This setting is only used in combination with :term:`until`." roles: List of roles to be imported into the play 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. -serial: Defines the 'batch' of hosts to execute the current play until the end. +serial: | + Explicitly define how Ansible batches the execution of the current play on the play's target + + .. seealso:: :ref:`rolling_update_batch_size` + 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. tasks: Main list of tasks to execute in the play, they run after :term:`roles` and before :term:`post_tasks`. diff --git a/docs/templates/playbooks_keywords.rst.j2 b/docs/templates/playbooks_keywords.rst.j2 index c5bd847c62..c16321e0c7 100644 --- a/docs/templates/playbooks_keywords.rst.j2 +++ b/docs/templates/playbooks_keywords.rst.j2 @@ -1,11 +1,16 @@ -Directives Glossary -=================== +Playbook Keywords +================= -Here we list the common playbook objects and 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. +These are the keywords available on common playbook objects. + +.. note:: Please note: + + * Aliases for the directives are not reflected here, nor are mutable one. For example, + :term:`action` in task can be substituted by the name of any Ansible module. + * The keywords do not have ``version_added`` information at this time + * Some keywords set defaults for the objects inside of them rather than for the objects + themselves -Be aware that this reflects the 'current development branch' and that the keywords do not have 'version_added' information. .. contents:: :local: @@ -19,8 +24,7 @@ Be aware that this reflects the 'current development branch' and that the keywor {% for attribute in oblist[name]|sort %} {{ attribute }} - {{ oblist[name][attribute] }} + {{ oblist[name][attribute] |indent(8) }} {% endfor %} - {% endfor %} |