diff --git a/docs/bin/plugin_formatter.py b/docs/bin/plugin_formatter.py index ec73594e530..65d803faa9d 100755 --- a/docs/bin/plugin_formatter.py +++ b/docs/bin/plugin_formatter.py @@ -301,6 +301,10 @@ def get_plugin_info(module_dir, limit_to=None, verbose=False): # Start at the second directory because we don't want the "vendor" mod_path_only = os.path.dirname(module_path[len(module_dir):]) + # Find the subcategory for each module + relative_dir = mod_path_only.split('/')[1] + sub_category = mod_path_only[len(relative_dir) + 2:] + primary_category = '' module_categories = [] # build up the categories that this module belongs to @@ -338,6 +342,7 @@ def get_plugin_info(module_dir, limit_to=None, verbose=False): 'returndocs': returndocs, 'categories': module_categories, 'primary_category': primary_category, + 'sub_category': sub_category, } # keep module tests out of becoming module docs @@ -587,7 +592,7 @@ def process_categories(plugin_info, categories, templates, output_dir, output_na write_data(text, output_dir, category_filename) -def process_support_levels(plugin_info, templates, output_dir, plugin_type): +def process_support_levels(plugin_info, categories, templates, output_dir, plugin_type): supported_by = {'Ansible Core Team': {'slug': 'core_supported', 'modules': [], 'output': 'core_maintained.rst', @@ -650,9 +655,24 @@ These modules are currently shipped with Ansible, but will most likely be shippe else: raise AnsibleError('Unknown supported_by value: %s' % info['metadata']['supported_by']) - # Render the module lists + # Render the module lists based on category and subcategory for maintainers, data in supported_by.items(): + subcategories = {} + subcategories[''] = {} + for module in data['modules']: + new_cat = plugin_info[module]['sub_category'] + category = plugin_info[module]['primary_category'] + if category not in subcategories: + subcategories[category] = {} + subcategories[category][''] = {} + subcategories[category]['']['_modules'] = [] + if new_cat not in subcategories[category]: + subcategories[category][new_cat] = {} + subcategories[category][new_cat]['_modules'] = [] + subcategories[category][new_cat]['_modules'].append(module) + template_data = {'maintainers': maintainers, + 'subcategories': subcategories, 'modules': data['modules'], 'slug': data['slug'], 'module_info': plugin_info, @@ -747,7 +767,7 @@ def main(): process_categories(plugin_info, categories, templates, output_dir, category_list_name_template, plugin_type) # Render all the categories for modules - process_support_levels(plugin_info, templates, output_dir, plugin_type) + process_support_levels(plugin_info, categories, templates, output_dir, plugin_type) if __name__ == '__main__': diff --git a/docs/templates/modules_by_support.rst.j2 b/docs/templates/modules_by_support.rst.j2 index 368a2f0b0d3..eced773f3df 100644 --- a/docs/templates/modules_by_support.rst.j2 +++ b/docs/templates/modules_by_support.rst.j2 @@ -3,14 +3,43 @@ {# avoids rST "isn't included in any toctree" errors for module index docs #} :orphan: +**************************@{ '*' * maintainers | length }@ Modules Maintained by the @{ maintainers }@ -``````````````````````````@{ '`' * maintainers | length }@ +**************************@{ '*' * maintainers | length }@ + +.. contents:: + :local: + +{% for category, data in subcategories.items() | sort %} + +{% if category.lower() %} +.. _@{ category.lower() + '_' + slug.lower() + '_categories' }@: +{% else %} +.. _@{ slug.lower() + '_categories' }@: +{% endif %} + +@{ category.title() }@ +@{ '=' * category | length }@ + +{% for name, info in data.items() | sort %} + +{% if name.lower() %} +.. _@{ name.lower() + '_' + category + '_' + slug.lower() + '_' + plugin_type + 's' }@: +{% else %} +.. _@{ slug.lower() + '_' + category }@: +{% endif %} + +@{ name.title() }@ +@{ '-' * name | length }@ + +{% for module in info['_modules'] | sort %} + * :ref:`@{ module }@_@{plugin_type}@`{% if module_info[module]['deprecated'] %} **(D)** {% endif%} +{% endfor %} + +{% endfor %} -{% for module in modules | sort %} - * :ref:`@{ module }@_@{plugin_type}@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} {% endfor %} .. note:: - **(D)**: 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. -