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.

docs/bin/plugin_formatter.py

@@ -125,12 +125,13 @@ def write_data(text, options, outputname, module):
 #####################################################################################
 
 
-def list_modules(module_dir, depth=0):
+def list_modules(module_dir, depth=0, limit_to_modules="all"):
     ''' returns a hash of categories, each category being a hash of module names to file paths '''
 
     categories = dict()
     module_info = dict()
     aliases = defaultdict(set)
+    module_limit = limit_to_modules.split(",")
 
     # * windows powershell modules have documentation stubs in python docstring
     #   format (they are not executed) so skip the ps1 format files
@@ -167,8 +168,12 @@ def list_modules(module_dir, depth=0):
             aliases[source].add(module)
             continue
 
-        category[module] = module_path
-        module_info[module] = module_path
+        # Limit documentation building only to passed-in modules. The "none"
+        # below is not a typo (it should not be None). String "none" denotes
+        # don't build any module documentation.
+        if "none" not in module_limit and ("all" in module_limit or module in module_limit):
+            category[module] = module_path
+            module_info[module] = module_path
 
     # keep module tests out of becoming module docs
     if 'test' in categories:
@@ -194,6 +199,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="all",
+                 help="Limit building module documentation to comma-separated list of modules. Specify 'all' or 'none' for all/no modules.")
     p.add_option('-V', action='version', help='Show version number and exit')
     return p
 
@@ -447,7 +454,7 @@ def main():
 
     env, template, outputname = jinja2_environment(options.template_dir, options.type)
 
-    mod_info, categories, aliases = list_modules(options.module_dir)
+    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('_')]

docs/docsite/Makefile

@@ -8,6 +8,10 @@ else
 CPUS ?= $(shell nproc)
 endif
 
+# Assume we are building documentation for all modules unless specified
+# otherwise via environment variable.
+MODULES ?= all
+
 all: docs
 
 docs: clean htmldocs
@@ -44,7 +48,7 @@ keywords: $(FORMATTER) ../templates/playbooks_keywords.rst.j2
 	PYTHONPATH=../../lib $(DUMPER) --template-dir=../templates --output-dir=rst/ -d ./keyword_desc.yml
 
 modules: $(FORMATTER) ../templates/plugin.rst.j2
-	PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/
+	PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/ -l $(MODULES)
 
 staticmin:
 	cat _themes/srtd/static/css/theme.css | sed -e 's/^[ 	]*//g; s/[ 	]*$$//g; s/\([:{;,]\) /\1/g; s/ {/{/g; s/\/\*.*\*\///g; /^$$/d' | sed -e :a -e '$$!N; s/\n\(.\)/\1/; ta' > _themes/srtd/static/css/theme.min.css

docs/docsite/README.md

@@ -14,6 +14,11 @@ such as link references, you may install sphinx and build the documentation by r
 To include module documentation you'll need to run `make webdocs` at the top level of the repository.  The generated
 html files are in docsite/htmlout/.
 
+To limit module documentation building to a specific module, run `MODULES=NAME
+make webdocs` instead. This should make testing module documentation syntax much
+faster. Instead of a single module, you can also specify a comma-separated list
+of modules, or keywords `all` and `none`.
+
 If you do not want to learn the reStructuredText format, you can also [file issues] about
 documentation problems on the Ansible GitHub project.
 

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -338,6 +338,13 @@ Put your completed module file into the ``lib/ansible/modules/$CATEGORY/`` direc
 run the command: ``make webdocs``. The new 'modules.html' file will be
 built in the ``docs/docsite/_build/html/$MODULENAME_module.html`` directory.
 
+In order to limit module documentation building to the module you are working on
+(and therefore speeding the build process by quite a bit), run the command:
+``MODULES=$MODULENAME make webdocs``. The ``MODULES`` environment variable
+accepts a comma-separated list of module names, or special keywords ``all`` (for
+building documentation for all modules) and ``none`` (for skipping the module
+documentation building process entirely).
+
 To test your documentation against your ``argument_spec`` you can use ``validate-modules``. Note that this option isn't currently enabled in Shippable due to the time it takes to run.
 
 .. code-block:: bash