quick and dirty module doc updates (#18944)
clean up core/extras, plumb in basic metadata display
This commit is contained in:
Matt Davis
Matt Clay
parent
250b0dff46
commit
0b47c908eb
4 changed files with 19 additions and 26 deletions
|
|
@ -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>`_.
|
||||
|
||||
|
|
|
|||
|
|
@ -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>`_
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
Loading…
Reference in a new issue