Skip to content

A
ansible
Commit 83f277cf by Michael DeHaan
Options

Various tweaking to get the module formatter to work for 'make docs' in the docs… 

Various tweaking to get the module formatter to work for 'make docs' in the docs project.  Likely the templates for other module formatting types will have to change
by the time I'm done.
parent 9a7a2a4d
Showing with 140 additions and 127 deletions
hacking/module_formatter.py
......@@ -53,7 +53,7 @@ options:
with B(bold), etc. work too.
- remove:
required: false
choices: [ yes, no, maybe, perhaps ]
choices: [ yes, no ]
default: "maybe"
aliases: [ kill, killme, delete ]
description:
......@@ -90,7 +90,6 @@ def html_ify(text):
t = _MODULE.sub("<span class='module'>" + r"\1" + "</span>", t)
t = _URL.sub("<a href='" + r"\1" + "'>" + r"\1" + "</a>", t)
t = _CONST.sub("<code>" + r"\1" + "</code>", t)
return t
def man_ify(text):
......@@ -121,7 +120,8 @@ def rst_xline(width, char="="):
return char * width
env = Environment(loader=FileSystemLoader('templates'),
# FIXME: path should be configurable
env = Environment(loader=FileSystemLoader('../ansible/hacking/templates/'),
variable_start_string="@{",
variable_end_string="}@",
)
......@@ -207,6 +207,8 @@ def main():
print "Need module_dir"
sys.exit(1)
# TODO: make template dir configurable
if args.type == 'latex':
env.filters['jpfunc'] = latex_ify
template = env.get_template('latex.j2')
......@@ -221,6 +223,7 @@ def main():
outputname = "ansible.%s.man"
if args.type == 'rst':
env.filters['jpfunc'] = rst_ify
env.filters['html_ify'] = html_ify
env.filters['fmt'] = rst_fmt
env.filters['xline'] = rst_xline
template = env.get_template('rst.j2')
......
hacking/templates/rst.j2
......@@ -19,15 +19,26 @@
{% endfor %}
{% if options is defined -%}
@{ xline(10, "=") }@ @{xline(10)}@ @{xline(10)}@ @{xline(60)}@
@{ "parameter" | fmt('%-10s')}@ @{ "required" | fmt('%-10s')}@ @{ "default" | fmt('%-10s')}@ @{ "comments" | fmt('%-60s')}@
@{ xline(10, "=") }@ @{xline(10)}@ @{xline(10)}@ @{xline(60)}@ {% for o in options -%}
{% for opt, v in o.iteritems() %}
{% if v['required'] %}{% set required = 'yes' %}{% else %}{% set required = ' ' %}{% endif -%}
@{opt |fmt("%-10s") }@ @{ required|fmt('%-10s') }@ @{ v['default']|fmt('%-10s') }@ {% for desc in v.description -%}@{ desc | jpfunc }@{% endfor -%}
{% endfor -%}
{% endfor %}
@{ xline(10, "=") }@ @{xline(10)}@ @{xline(10)}@ @{xline(60)}@
.. raw:: html
<table>
<tr>
<td>parameter</td>
<td>required</td>
<td>default</td>
<td>choices</td>
<td>comments</td>
</tr>
{% for (k,v) in options.iteritems() %}
<tr>
<td>@{ k }@</td>
<td>@{ v.get('required',False) }@</td>
<td>@{ v['default'] }@</td>
<td><ul>{% for choice in v.get('choices',[]) -%}<li>@{ choice }@</li>{% endfor -%}</ul></td>
<td>{% for desc in v.description -%}@{ desc | html_ify }@{% endfor -%}</td>
</tr>
{% endfor %}
</table>
{% endif %}
FIXME: examples!
FIXME: include the examples here!
library/file
......@@ -38,21 +38,21 @@ description:
the file module - including M(copy), M(template), and M(assmeble).
version_added: "0.1"
options:
- dest:
description:
- defines the file being managed, unless when used with I(state=link), and then sets the destination to create a symbolic link to using I(src)
required: true
default: []
aliases: []
- state:
description:
- If directory, all immediate subdirectories will be created if they do not exist. If I(file), the file will NOT be created if it does not exist, see the M(copy) or M(template) module if you want that behavior. If I(link), the symbolic link will be created or changed. If absent, directories will be recursively deleted, and files or symlinks will be unlinked.
required: false
default: file
choices: [ file, link, directory, absent ]
- mode:
description:
- mode the file or directory should be, such as 0644 as would be fed to I(chmod). English modes like B(g+x) are not yet supported
dest:
description:
- defines the file being managed, unless when used with I(state=link), and then sets the destination to create a symbolic link to using I(src)
required: true
default: []
aliases: []
state:
description:
- If directory, all immediate subdirectories will be created if they do not exist. If I(file), the file will NOT be created if it does not exist, see the M(copy) or M(template) module if you want that behavior. If I(link), the symbolic link will be created or changed. If absent, directories will be recursively deleted, and files or symlinks will be unlinked.
required: false
default: file
choices: [ file, link, directory, absent ]
mode:
description:
- mode the file or directory should be, such as 0644 as would be fed to I(chmod). English modes like B(g+x) are not yet supported
examples:
- code: file path=/etc/foo.conf owner=foo group=foo mode=0644
description: Example from Ansible Playbooks
......
library/get_url
......@@ -33,32 +33,32 @@ description:
server must have direct access to the remote resource.
version_added: "0.6"
options:
- url:
description:
- HTTP, HTTPS, or FTP URL
required: true
default: null
aliases: []
- dest:
description:
- absolute path of where to download the file to.
- If I(dest) is a directory, the basename of the file on the remote server will be used. If a directory, I(thirsty=yes) must also be set.
required: true
default: null
- thirsty:
description:
- if C(yes), will download the file every time and replace the
file if the contents change. if C(no), the file will only be downloaded if
the destination does not exist. Generally should be C(yes) only for small
local files. prior to 0.6, acts if C(yes) by default.
version_added: "0.7"
required: false
choices: [ "yes", "no" ]
default: "no"
- others:
description:
- all arguments accepted by the M(file) module also work here
required: false
url:
description:
- HTTP, HTTPS, or FTP URL
required: true
default: null
aliases: []
dest:
description:
- absolute path of where to download the file to.
- If I(dest) is a directory, the basename of the file on the remote server will be used. If a directory, I(thirsty=yes) must also be set.
required: true
default: null
thirsty:
description:
- if C(yes), will download the file every time and replace the
file if the contents change. if C(no), the file will only be downloaded if
the destination does not exist. Generally should be C(yes) only for small
local files. prior to 0.6, acts if C(yes) by default.
version_added: "0.7"
required: false
choices: [ "yes", "no" ]
default: "no"
others:
description:
- all arguments accepted by the M(file) module also work here
required: false
examples:
- code: get_url url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440
description: Obtain and install config file
......
library/ini_file
......@@ -29,41 +29,40 @@ description:
sections if they don't exist.
version_added: "0.9"
options:
- dest:
description:
- Path to the INI-style file; this file is created if required
required: true
default: null
aliases: []
- section:
description:
- Section name in INI file. This is added if C(state=present) automatically when
a single value is being set.
required: true
default: null
- option:
description:
- if set (required for changing a I(value)), this is the name of the option.
- May be omitted if adding/removing a whole I(section).
required: false
default: []
- value:
description:
- the string value to be associated with an I(option). May be omitted when
removing an I(option).
required: false
default: []
- backup:
description:
- Create a backup file including the timestamp information so you can get
the original file back if you somehow clobbered it incorrectly.
required: false
default: no
choices: [ "yes", "no" ]
- others:
description:
- all arguments accepted by the M(file) module also work here
required: false
dest:
description:
- Path to the INI-style file; this file is created if required
required: true
default: null
aliases: []
section:
description:
- Section name in INI file. This is added if C(state=present) automatically when
a single value is being set.
required: true
default: null
option:
description:
- if set (required for changing a I(value)), this is the name of the option.
- May be omitted if adding/removing a whole I(section).
required: false
default: []
value:
description:
- the string value to be associated with an I(option). May be omitted when removing an I(option).
required: false
default: []
backup:
description:
- Create a backup file including the timestamp information so you can get
the original file back if you somehow clobbered it incorrectly.
required: false
default: no
choices: [ "yes", "no" ]
others:
description:
- all arguments accepted by the M(file) module also work here
required: false
notes:
- While it is possible to add an I(option) without specifying a I(value), this makes
no sense.
......
library/lineinfile
......@@ -31,44 +31,44 @@ description:
file only. For other cases, see the M(copy) or M(template) modules.
version_added: "0.7"
options:
- name:
required: true
description:
- The file to modify
- regexp:
required: true
description:
- The regular expression to look for in the file. For I(state=present),
the pattern to replace. For I(state=absent), the pattern of the line
to remove.
- state:
required: false
choices: [ present, absent ]
default: "present"
aliases: []
description:
- Whether the line should be there or not.
- line:
required: false
description:
- Required for I(state=present). The line to insert/replace into the
file. Must match the value given to C(regexp).
- insertafter:
required: false
default: EOF
description:
- Used with I(state=present). If specified, the line will be inserted
after the specified regular expression. Two special values are
available; C(BOF) for inserting the line at the beginning of the
file, and C(EOF) for inserting the line at the end of the file.
choices: [ BOF, EOF ]
default: EOF
- backup:
required: false
default: no
description:
- Create a backup file including the timestamp information so you can
get the original file back if you somehow clobbered it incorrectly.
name:
required: true
description:
- The file to modify
regexp:
required: true
description:
- The regular expression to look for in the file. For I(state=present),
the pattern to replace. For I(state=absent), the pattern of the line
to remove.
state:
required: false
choices: [ present, absent ]
default: "present"
aliases: []
description:
- Whether the line should be there or not.
line:
required: false
description:
- Required for I(state=present). The line to insert/replace into the
file. Must match the value given to C(regexp).
insertafter:
required: false
default: EOF
description:
- Used with I(state=present). If specified, the line will be inserted
after the specified regular expression. Two special values are
available; C(BOF) for inserting the line at the beginning of the
file, and C(EOF) for inserting the line at the end of the file.
choices: [ BOF, EOF ]
default: EOF
backup:
required: false
default: no
description:
- Create a backup file including the timestamp information so you can
get the original file back if you somehow clobbered it incorrectly.
examples:
- code: lineinfile name=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
- code: lineinfile name=/etc/sudoers state=absent regexp="^%wheel"
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment