Allow modules to be categorized, and also sort them when generating the documentation.

docsite/latest/rst/modules.rst

@@ -62,7 +62,7 @@ Let's see what's available in the Ansible module library, out of the box:
 
 
 Writing your own modules
-````````````````````````
+========================
 
 See :doc:`moduledev`.
 

hacking/module_formatter.py

@@ -18,6 +18,7 @@
 #
 
 import os
+import glob
 import sys
 import yaml
 import codecs
@@ -137,6 +138,20 @@ def boilerplate():
         print >>sys.stderr, "Missing example boiler plate: %S" % EXAMPLE_YAML
     print file(EXAMPLE_YAML).read()
 
+def list_modules(module_dir):
+    categories = {}
+    files = glob.glob("%s/*" % module_dir)
+    for d in files:
+        if os.path.isdir(d):
+            files2 = glob.glob("%s/*" % d)
+            for f in files2:
+                tokens = f.split("/")
+                module = tokens[-1]
+                category = tokens[-2]
+                if not category in categories:
+                    categories[category] = {}
+                categories[category][module] = f
+    return categories
 
 def main():
 
@@ -274,12 +289,30 @@ def main():
 
     # Temporary variable required to genrate aggregated content in 'js' format.
     js_data = []
-    for module in sorted(os.listdir(options.module_dir)):
+
+    categories = list_modules(options.module_dir)
+    last_category = None
+    category_names = categories.keys()
+    category_names.sort()
+ 
+    for category in category_names:
+        module_map = categories[category]
+ 
+        category = category.replace("_"," ")
+        category = category.title()
+
+        modules = module_map.keys()
+        modules.sort()
+
+        for module in modules:
+            fname = module_map[module]
+
             if len(options.module_list):
                 if not module in options.module_list:
                     continue
 
-        fname = os.path.join(options.module_dir, module)
+            # fname = os.path.join(options.module_dir, module)
+
             extra = os.path.join("inc", "%s.tex" % module)
 
             # probably could just throw out everything with extensions
@@ -317,7 +350,18 @@ def main():
                 doc['ansible_version']  = options.ansible_version
                 doc['plainexamples']    = examples  #plain text
 
+                # BOOKMARK: here is where we build the table of contents...
+
                 if options.includes_file is not None and includefmt != "":
+
+                    if last_category != category:
+                         incfile.write("\n\n")
+                         incfile.write(category)
+                         incfile.write("\n")
+                         incfile.write('=' * len(category))
+                         incfile.write("\n\n")
+                         last_category = category
+
                     incfile.write(includefmt % module)
 
                 if options.verbose:

lib/ansible/utils/plugins.py

@@ -92,8 +92,15 @@ class PluginLoader(object):
         ret += self._extra_dirs
         for basedir in _basedirs:
             fullpath = os.path.join(basedir, self.subdir)
+            if os.path.isdir(fullpath):
+                files = glob.glob("%s/*" % fullpath)
+                for file in files:
+                    if os.path.isdir(file):
+                        ret.append(file)    
+            else:
                 if fullpath not in ret:
                     ret.append(fullpath)
+                
         ret += self.config.split(os.pathsep)
         ret += self._get_package_path()