From 0b47c908ebe3b6816ba34ecd6c1c40ed51fa7e4f Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Wed, 7 Dec 2016 14:50:17 -0800 Subject: [PATCH] quick and dirty module doc updates (#18944) clean up core/extras, plumb in basic metadata display --- docsite/rst/modules_core.rst | 4 ++-- docsite/rst/modules_extra.rst | 4 ++-- hacking/module_formatter.py | 29 ++++++++++------------------- hacking/templates/rst.j2 | 8 +++++--- 4 files changed, 19 insertions(+), 26 deletions(-) diff --git a/docsite/rst/modules_core.rst b/docsite/rst/modules_core.rst index 4d692dad15..58114b93ce 100644 --- a/docsite/rst/modules_core.rst +++ b/docsite/rst/modules_core.rst @@ -4,9 +4,9 @@ Core Modules These are modules that the core ansible team maintains and will always ship with ansible itself. They will also receive slightly higher priority for all requests than those in the "extras" repos. -The source of these modules is hosted on GitHub in the `ansible-modules-core `_ repo. +The source of these modules is hosted on GitHub in the `ansible `_ repo. -If you believe you have found a bug in a core module and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-core `_ to see if a bug has already been filed. If not, we would be grateful if you would file one. +If you believe you have found a bug in a core module and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible `_ to see if a bug has already been filed. If not, we would be grateful if you would file one. Should you have a question rather than a bug report, inquiries are welcome on the `ansible-project google group `_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group `_. diff --git a/docsite/rst/modules_extra.rst b/docsite/rst/modules_extra.rst index b6d7639d15..bcfdc62959 100644 --- a/docsite/rst/modules_extra.rst +++ b/docsite/rst/modules_extra.rst @@ -6,10 +6,10 @@ Non-core modules are still fully usable, but may receive slightly lower response Popular "extras" modules may be promoted to core modules over time. -The source for these modules is hosted on GitHub in the `ansible-modules-extras `_ repo. +The source for these modules is hosted on GitHub in the `ansible `_ repo. If you believe you have found a bug in an extras module and are already running the latest stable or development version of Ansible, -first look in the `issue tracker at github.com/ansible/ansible-modules-extras `_ +first look in the `issue tracker at github.com/ansible/ansible `_ to see if a bug has already been filed. If not, we would be grateful if you could file one. Should you have a question rather than a bug report, inquiries are welcome on the `ansible-project google group `_ diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index e23994e371..1ae4d2a2fb 100755 --- a/hacking/module_formatter.py +++ b/hacking/module_formatter.py @@ -64,7 +64,6 @@ _URL = re.compile(r"U\(([^)]+)\)") _CONST = re.compile(r"C\(([^)]+)\)") DEPRECATED = " (D)" -NOTCORE = " (E)" ##################################################################################### def rst_ify(text): @@ -258,15 +257,14 @@ def process_module(module, options, env, template, outputname, module_map, alias sys.stderr.write("*** ERROR: MODULE MISSING DOCUMENTATION: %s, %s ***\n" % (fname, module)) sys.exit(1) + if metadata is None: + sys.stderr.write("*** ERROR: MODULE MISSING METADATA: %s, %s ***\n" % (fname, module)) + sys.exit(1) + if deprecated and 'deprecated' not in doc: sys.stderr.write("*** ERROR: DEPRECATED MODULE MISSING 'deprecated' DOCUMENTATION: %s, %s ***\n" % (fname, module)) sys.exit(1) - if "/core/" in fname: - doc['core'] = True - else: - doc['core'] = False - if module in aliases: doc['aliases'] = aliases[module] @@ -310,6 +308,8 @@ def process_module(module, options, env, template, outputname, module_map, alias doc['now_date'] = datetime.date.today().strftime('%Y-%m-%d') doc['ansible_version'] = options.ansible_version doc['plainexamples'] = examples #plain text + doc['metadata'] = metadata + if returndocs: try: doc['returndocs'] = yaml.safe_load(returndocs) @@ -330,15 +330,13 @@ def process_module(module, options, env, template, outputname, module_map, alias ##################################################################################### -def print_modules(module, category_file, deprecated, core, options, env, template, outputname, module_map, aliases): +def print_modules(module, category_file, deprecated, options, env, template, outputname, module_map, aliases): modstring = module if modstring.startswith('_'): modstring = module[1:] modname = modstring if module in deprecated: modstring = modstring + DEPRECATED - elif module not in core: - modstring = modstring + NOTCORE category_file.write(" %s - %s <%s_module>\n" % (to_bytes(modstring), to_bytes(rst_ify(module_map[module][1])), to_bytes(modname))) @@ -374,21 +372,16 @@ def process_category(category, categories, options, env, template, outputname): modules = [] deprecated = [] - core = [] for module in module_map.keys(): if isinstance(module_map[module], dict): for mod in (m for m in module_map[module].keys() if m in module_info): if mod.startswith("_"): deprecated.append(mod) - elif '/core/' in module_info[mod][0]: - core.append(mod) else: if module not in module_info: continue if module.startswith("_"): deprecated.append(module) - elif '/core/' in module_info[module][0]: - core.append(module) modules.append(module) modules.sort(key=lambda k: k[1:] if k.startswith('_') else k) @@ -409,7 +402,7 @@ def process_category(category, categories, options, env, template, outputname): sections.append(module) continue else: - print_modules(module, category_file, deprecated, core, options, env, template, outputname, module_info, aliases) + print_modules(module, category_file, deprecated, options, env, template, outputname, module_info, aliases) sections.sort() for section in sections: @@ -420,14 +413,12 @@ def process_category(category, categories, options, env, template, outputname): section_modules.sort(key=lambda k: k[1:] if k.startswith('_') else k) #for module in module_map[section]: for module in (m for m in section_modules if m in module_info): - print_modules(module, category_file, deprecated, core, options, env, template, outputname, module_info, aliases) + print_modules(module, category_file, deprecated, options, env, template, outputname, module_info, aliases) category_file.write("""\n\n .. note:: - %s: This marks a module as deprecated, which means a module is kept for backwards compatibility but usage is discouraged. The module documentation details page may explain more about this rationale. - - %s: This marks a module as 'extras', which means it ships with ansible but may be a newer module and possibly (but not necessarily) less actively maintained than 'core' modules. - - Tickets filed on modules are filed to different repos than those on the main open source project. Core module tickets should be filed at `ansible/ansible-modules-core on GitHub `_, extras tickets to `ansible/ansible-modules-extras on GitHub `_ -""" % (DEPRECATED, NOTCORE)) +""" % DEPRECATED) category_file.close() # TODO: end a new category file diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index 5d292aaa50..d1da34b77c 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -168,9 +168,11 @@ Notes {% endfor %} {% endif %} - {% if not deprecated %} - {% if core %} +Module Status: @{ ','.join(metadata.status) }@ +-------------------- + + {% if metadata.supported_by == 'core' %} This is a Core Module --------------------- @@ -179,7 +181,7 @@ For more information on what this means please read :doc:`modules_core` {% else %} -This is an Extras Module +This is module is supported by: @{ metadata.supported_by }@ ------------------------ For more information on what this means please read :doc:`modules_extra`