Implement ability to limit module documentation building (#24576)

* Implement ability to limit module documentation building:

- Added new option to plugin_formatter.py to support passing-in a list of
  modules for which the documentation should be built.
- Updated docuemtnation Makefile to allow specifying list of modules via
  environment variables (defaulting to all modules).
- Update instructions for building documentation and module development to
  include commands and description of limiting module documentation builds.

* Updated implementation for limiting module documentation building:

- Pass list of modules (or None) to list_modules function instead of string.
- Move conversion of module list to argument parsing code.
- No special keywords. Default ("") means build all modules. For no modules just
  specify non-existing module name.
- Updated documentation to reflect the changes.

* Updated implementation for limiting module documentation building:

- Use better default value, and don't treat "" as special case.
- Conditionally invoke different variants of command in Makefile instead of
  using special value "".

* Minor edits

Wording tweak

docs/bin/plugin_formatter.py

@@ -117,7 +117,7 @@ def write_data(text, options, outputname, module):
         print(text)
 
 
-def list_modules(module_dir, depth=0):
+def list_modules(module_dir, depth=0, limit_to_modules=None):
     ''' returns a hash of categories, each category being a hash of module names to file paths '''
 
     categories = dict()
@@ -159,8 +159,11 @@ def list_modules(module_dir, depth=0):
             aliases[source].add(module)
             continue
 
-        category[module] = module_path
-        module_info[module] = module_path
+        # If requested, limit module documentation building only to passed-in
+        # modules.
+        if limit_to_modules is None or module.lower() in limit_to_modules:
+            category[module] = module_path
+            module_info[module] = module_path
 
     # keep module tests out of becoming module docs
     if 'test' in categories:
@@ -185,6 +188,8 @@ def generate_parser():
     p.add_option("-v", "--verbose", action='store_true', default=False, help="Verbose")
     p.add_option("-o", "--output-dir", action="store", dest="output_dir", default=None, help="Output directory for module files")
     p.add_option("-I", "--includes-file", action="store", dest="includes_file", default=None, help="Create a file containing list of processed modules")
+    p.add_option("-l", "--limit-to-modules", action="store", dest="limit_to_modules", default=None,
+                 help="Limit building module documentation to comma-separated list of modules. Specify non-existing module name for no modules.")
     p.add_option('-V', action='version', help='Show version number and exit')
     return p
 
@@ -435,7 +440,11 @@ def main():
 
     env, template, outputname = jinja2_environment(options.template_dir, options.type)
 
-    mod_info, categories, aliases = list_modules(options.module_dir)
+    # Convert passed-in limit_to_modules to None or list of modules.
+    if options.limit_to_modules is not None:
+        options.limit_to_modules = [s.lower() for s in options.limit_to_modules.split(",")]
+
+    mod_info, categories, aliases = list_modules(options.module_dir, limit_to_modules=options.limit_to_modules)
     categories['all'] = mod_info
     categories['_aliases'] = aliases
     category_names = [c for c in categories.keys() if not c.startswith('_')]