Keywords docs ()

* Fixup keyword dumping

* Clarify introductory text
* Turn links in the keyword description into seealso entries in the rst.

* Have plugin_formatter cleanup trailing whitespace

The indent filter in jinja2 < 2.10 indents blank lines by default which
leads to trailing whitespace.  Cleanup after that filter.

* Edits

* Copy edit

(cherry picked from commit e07cbb033f)
This commit is contained in:
Toshio Kuratomi 2017-11-10 16:59:26 -08:00
parent 29bdd0b326
commit 52d2245b26
5 changed files with 67 additions and 31 deletions

2
.gitignore vendored
View file

@ -35,7 +35,7 @@ docs/docsite/rst/*_module.rst
docs/docsite/rst/modules_by_category.rst
docs/docsite/rst/network_maintained.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/*.html
docs/docsite/rst/ansible.rst

View file

@ -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")
@ -65,5 +68,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)

View file

@ -30,6 +30,9 @@ 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:
@ -39,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
@ -382,6 +386,9 @@ def process_modules(module_map, templates, outputname, output_dir, ansible_versi
doc['returndocs'] = None
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)

View file

@ -1,51 +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_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: "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.
.. 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`.

View file

@ -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 %}