Keywords docs (#32807)
* 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:
parent
29bdd0b326
commit
52d2245b26
5 changed files with 67 additions and 31 deletions
.gitignore
docs
2
.gitignore
vendored
2
.gitignore
vendored
|
@ -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
|
||||
|
|
|
@ -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)
|
||||
|
|
|
@ -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)
|
||||
|
||||
|
|
|
@ -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`.
|
||||
|
|
20
docs/templates/playbooks_keywords.rst.j2
vendored
20
docs/templates/playbooks_keywords.rst.j2
vendored
|
@ -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 %}
|
||||
|
|
Loading…
Reference in a new issue