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/docsite/Makefile

@@ -50,7 +50,12 @@ 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
+# Limit building of module documentation if requested.
+ifdef MODULES
+	PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/ -l $(MODULES)	
+else
 	PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/
+endif
 
 testing:
 	$(TESTING_FORMATTER)

docs/docsite/README.md

@@ -14,6 +14,12 @@ 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. In order to skip building documentation for all modules, specify
+non-existing module name, for example `MODULES=none make webdocs`.
+
 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

@@ -383,6 +383,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 speed up the build process, you can limit the documentation build to 
+only include modules you specify, or no modules at all. To do this, run the command:
+``MODULES=$MODULENAME make webdocs``. The ``MODULES`` environment variable
+accepts a comma-separated list of module names. To skip building
+documentation for all modules, specify a non-existent module name, for example:
+``MODULES=none make webdocs``.
+
 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