quick and dirty module doc updates (#18944)

clean up core/extras, plumb in basic metadata display
This commit is contained in:
Matt Davis 2016-12-07 14:50:17 -08:00 committed by Matt Clay
parent 250b0dff46
commit 0b47c908eb
4 changed files with 19 additions and 26 deletions

View file

@ -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 <http://github.com/ansible/ansible-modules-core>`_ repo.
The source of these modules is hosted on GitHub in the `ansible <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_ 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 <http://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 <http://github.com/ansible/ansible/issues>`_ 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 <https://groups.google.com/forum/#!forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.

View file

@ -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 <http://github.com/ansible/ansible-modules-extras>`_ repo.
The source for these modules is hosted on GitHub in the `ansible <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_ 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 <http://github.com/ansible/ansible-modules-extras>`_
first look in the `issue tracker at github.com/ansible/ansible <http://github.com/ansible/ansible/issues>`_
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 <https://groups.google.com/forum/#!forum/ansible-project>`_

View file

@ -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 <http://github.com/ansible/ansible-modules-core>`_, extras tickets to `ansible/ansible-modules-extras on GitHub <http://github.com/ansible/ansible-modules-extras>`_
""" % (DEPRECATED, NOTCORE))
""" % DEPRECATED)
category_file.close()
# TODO: end a new category file

View file

@ -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`