From 6ba706f7536971f9c5f7ce874e570a6c5c0353e0 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 17 Jul 2015 10:00:02 -0400 Subject: [PATCH] minor doc reformatting now version_added < 1.3 does not get shown, up from 1.0 option's version_added is also now filterd against this threshold module version_added is more prominent exaples now uses pure rst instead of intermingled with html formatting aliases now shown in description for options bad version fields now throw warnings instead of exceptions ansible-doc errors now show traceback in very very verbose mode, for easier debugging --- hacking/module_formatter.py | 29 ++++++++++++++++++--------- hacking/templates/rst.j2 | 39 +++++++++++++------------------------ lib/ansible/cli/doc.py | 1 + 3 files changed, 35 insertions(+), 34 deletions(-) diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index 72a4613adb..443e660958 100755 --- a/hacking/module_formatter.py +++ b/hacking/module_formatter.py @@ -31,6 +31,7 @@ import time import datetime import subprocess import cgi +import warnings from jinja2 import Environment, FileSystemLoader from ansible.utils import module_docs @@ -41,7 +42,7 @@ from ansible.utils.vars import merge_hash # if a module is added in a version of Ansible older than this, don't print the version added information # in the module documentation because everyone is assumed to be running something newer than this already. -TO_OLD_TO_BE_NOTABLE = 1.5 +TO_OLD_TO_BE_NOTABLE = 1.3 # Get parent directory of the directory this script lives in MODULEDIR=os.path.abspath(os.path.join( @@ -214,6 +215,17 @@ def jinja2_environment(template_dir, typ): return env, template, outputname ##################################################################################### +def too_old(added): + if not added: + return False + try: + added_tokens = str(added).split(".") + readded = added_tokens[0] + "." + added_tokens[1] + added_float = float(readded) + except ValueError as e: + warnings.warn("Could not parse %s: %s" % (added, str(e))) + return False + return (added_float < TO_OLD_TO_BE_NOTABLE) def process_module(module, options, env, template, outputname, module_map, aliases): @@ -271,15 +283,15 @@ def process_module(module, options, env, template, outputname, module_map, alias added = doc['version_added'] # don't show version added information if it's too old to be called out - if added: - added_tokens = str(added).split(".") - added = added_tokens[0] + "." + added_tokens[1] - added_float = float(added) - if added and added_float < TO_OLD_TO_BE_NOTABLE: - del doc['version_added'] + if too_old(added): + del doc['version_added'] if 'options' in doc: for (k,v) in doc['options'].iteritems(): + # don't show version added information if it's too old to be called out + if 'version_added' in doc['options'][k] and too_old(doc['options'][k]['version_added']): + del doc['options'][k]['version_added'] + continue all_keys.append(k) all_keys = sorted(all_keys) @@ -329,7 +341,7 @@ def process_category(category, categories, options, env, template, outputname): category_file = open(category_file_path, "w") print "*** recording category %s in %s ***" % (category, category_file_path) - # TODO: start a new category file + # start a new category file category = category.replace("_"," ") category = category.title() @@ -352,7 +364,6 @@ def process_category(category, categories, options, env, template, outputname): deprecated.append(module) elif '/core/' in module_map[module]: core.append(module) - modules.append(module) modules.sort() diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index a30e16e41f..fbf50f4922 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -10,6 +10,11 @@ @{ title }@ @{ '+' * title_len }@ +{% if version_added is defined -%} +.. versionadded:: @{ version_added }@ +{% endif %} + + .. contents:: :local: :depth: 1 @@ -21,10 +26,6 @@ # --------------------------------------------#} -{% if aliases is defined -%} -Aliases: @{ ','.join(aliases) }@ -{% endif %} - {% if deprecated is defined -%} DEPRECATED ---------- @@ -35,14 +36,13 @@ DEPRECATED Synopsis -------- -{% if version_added is defined -%} -.. versionadded:: @{ version_added }@ -{% endif %} - {% for desc in description -%} @{ desc | convert_symbols_to_format }@ {% endfor %} +{% if aliases is defined -%} +Aliases: @{ ','.join(aliases) }@ +{% endif %} {% if requirements %} Requirements @@ -79,37 +79,26 @@ Options {% else %} {% endif %} - {% for desc in v.description -%}@{ desc | html_ify }@{% endfor -%} - + {% for desc in v.description -%}
@{ desc | html_ify }@
{% endfor -%} {% if 'aliases' in v and v.aliases -%}
+
aliases: @{ v.aliases|join(', ') }@
{%- endif %} {% endfor %} +
{% endif %} - {% if examples or plainexamples -%} Examples -------- -.. raw:: html + :: {% for example in examples %} - {% if example['description'] %}

@{ example['description'] | html_ify }@

{% endif %} -

- 

+{% if example['description'] %}@{ example['description'] | indent(4, True) }@{% endif %}
 @{ example['code'] | escape | indent(4, True) }@
-
-

{% endfor %} -
- -{% if plainexamples %} - -:: - -@{ plainexamples | indent(4, True) }@ -{% endif %} +{% if plainexamples %}@{ plainexamples | indent(4, True) }@{% endif %} {% endif %} diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index 8638bf3897..910255cda7 100644 --- a/lib/ansible/cli/doc.py +++ b/lib/ansible/cli/doc.py @@ -122,6 +122,7 @@ class DocCLI(CLI): # probably a quoting issue. raise AnsibleError("Parsing produced an empty object.") except Exception, e: + self.display.vvv(traceback.print_exc()) raise AnsibleError("module %s missing documentation (or could not parse documentation): %s\n" % (module, str(e))) CLI.pager(text)