From 83f277cfe6de29d552164279c09ebf90bcd01cd8 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Thu, 27 Sep 2012 21:06:31 -0400 Subject: [PATCH] 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. --- hacking/module_formatter.py | 9 +++-- hacking/templates/rst.j2 | 31 ++++++++++----- library/file | 30 +++++++-------- library/get_url | 52 ++++++++++++------------- library/ini_file | 69 +++++++++++++++++---------------- library/lineinfile | 76 ++++++++++++++++++------------------- 6 files changed, 140 insertions(+), 127 deletions(-) diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index 7fad738e3a6..e3a691d6556 100755 --- a/hacking/module_formatter.py +++ b/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("" + r"\1" + "", t) t = _URL.sub("" + r"\1" + "", t) t = _CONST.sub("" + r"\1" + "", 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') diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index def117d219d..ac193cb9a57 100644 --- a/hacking/templates/rst.j2 +++ b/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 + + + + + + + + + + {% for (k,v) in options.iteritems() %} + + + + + + + + {% endfor %} +
parameterrequireddefaultchoicescomments
@{ k }@@{ v.get('required',False) }@@{ v['default'] }@
    {% for choice in v.get('choices',[]) -%}
  • @{ choice }@
    • {% endfor -%}
{% for desc in v.description -%}@{ desc | html_ify }@{% endfor -%}
{% endif %} - FIXME: examples! + FIXME: include the examples here! diff --git a/library/file b/library/file index e1ca84b738f..bf1eebf68b2 100755 --- a/library/file +++ b/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 diff --git a/library/get_url b/library/get_url index d3ac2bcccc5..68d9d8ccb72 100755 --- a/library/get_url +++ b/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 diff --git a/library/ini_file b/library/ini_file index 99fe9ee5a60..0a640b231fd 100755 --- a/library/ini_file +++ b/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. diff --git a/library/lineinfile b/library/lineinfile index 61bc1910c75..0166f6151c4 100755 --- a/library/lineinfile +++ b/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"