From 3eec7f18207193494c6b7b41d89fa8f03357589d Mon Sep 17 00:00:00 2001
From: Sandra McCann <samccann@redhat.com>
Date: Wed, 23 Jan 2019 14:21:23 -0500
Subject: [PATCH] Modules tocfix (#51077)

define & create subcategories, output by category and subcat
---
 docs/bin/plugin_formatter.py             | 26 +++++++++++++++--
 docs/templates/modules_by_support.rst.j2 | 37 +++++++++++++++++++++---
 2 files changed, 56 insertions(+), 7 deletions(-)

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.
-