Remove/update incorrect docs building documentation (#1128)

* MODULES= and PLUGINS= haven't worked since ansible-base 2.10.

* MODULES= no longer exists.

* Fix dash.

* Remove no longer correct parts.

* Mention --docker option.

Author: felixfontein

docs/docsite/Makefile

@@ -22,20 +22,6 @@ ifndef POTDIR
 	POTDIR = $(BUILDDIR)/gettext
 endif
 
-# Backwards compat for separate VARS
-PLUGIN_ARGS=
-ifdef MODULES
-ifndef PLUGINS
-	PLUGIN_ARGS = -l $(MODULES)
-else
-	PLUGIN_ARGS = -l $(MODULES),$(PLUGINS)
-endif
-else
-ifdef PLUGINS
-	PLUGIN_ARGS = -l $(PLUGINS)
-endif
-endif
-
 ANSIBLE_VERSION_ARGS=
 ifdef ANSIBLE_VERSION
 	ANSIBLE_VERSION_ARGS=--ansible-version=$(ANSIBLE_VERSION)
@@ -196,11 +182,11 @@ config: ../templates/config.rst.j2
 	$(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/ $(EXTRA_CONFIG_DUMPER_ARGS) ../../lib/ansible/config/base.yml
 
 plugins:
-	$(PLUGIN_FORMATTER) full -o rst $(ANSIBLE_VERSION_ARGS) $(EXTRA_PLUGIN_FORMATTER_ARGS) $(PLUGIN_ARGS)
+	$(PLUGIN_FORMATTER) full -o rst $(ANSIBLE_VERSION_ARGS) $(EXTRA_PLUGIN_FORMATTER_ARGS)
 
 # This only builds the plugin docs included with ansible-core
 core_plugins:
-	$(PLUGIN_FORMATTER) core -o rst $(EXTRA_PLUGIN_FORMATTER_ARGS) $(PLUGIN_ARGS)
+	$(PLUGIN_FORMATTER) core -o rst $(EXTRA_PLUGIN_FORMATTER_ARGS)
 
 epub:
 	(CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx epub)

docs/docsite/rst/community/documentation_contributions.rst

@@ -175,22 +175,18 @@ This process compiles all the links but provides minimal log output. If you're w
 Building all the rST pages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To build all the rST files without any module documentation:
+To build all the rST files with almost no module documentation:
 
 .. code-block:: bash
 
-   MODULES=none make webdocs
+   make coredocs
+
+This is building effectively the ansible-core documentation, as opposed to the Ansible community package documentation, which includes documentation for many collections.
 
 Building module docs and rST pages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To build documentation for a few modules included in ``ansible/ansible`` plus all the rST files, use a comma-separated list:
-
-.. code-block:: bash
-
-   MODULES=one_module,another_module make webdocs
-
-To build all the module documentation plus all the rST files:
+To build all the module documentation for the Ansible community package plus all the rST files:
 
 .. code-block:: bash
 
@@ -207,7 +203,7 @@ Advanced users can build one or more rST files with the sphinx utility directly.
 
   sphinx-build [options] sourcedir outdir [filenames...]
 
-You can specify file names, or ``–a`` for all files, or omit both to compile only new/changed files.
+You can specify file names, or ``-a`` for all files, or omit both to compile only new/changed files.
 
 For example:
 

docs/docsite/rst/dev_guide/testing_documentation.rst

@@ -9,23 +9,9 @@ Testing plugin documentation
 
 A quick test while developing is to use ``ansible-doc -t <plugin_type> <name>`` to see if it renders, you might need to add ``-M /path/to/module`` if the module is not somewhere Ansible expects to find it.
 
-Before you submit a plugin for inclusion in Ansible, you must test your documentation for correct HTML rendering and for modules to ensure that the argspec matches the documentation in your Python file.
-The community pages offer more information on :ref:`testing reStructuredText documentation <testing_documentation_locally>`.
+Before you submit a plugin for inclusion in ansible-core, you must run tests to ensure that the argspec matches the documentation in your Python file, and that the argspec's and documentation's structure is correct.
 
-For example, to check the HTML output of your module documentation:
-
-#. Ensure working :ref:`development environment <environment_setup>`.
-#. Install required Python packages (drop '--user' in venv/virtualenv):
-
-   .. code-block:: bash
-
-      pip install --user -r requirements.txt
-      pip install --user -r docs/docsite/requirements.txt
-
-#. Ensure your module is in the correct directory: ``lib/ansible/modules/mymodule.py`` or in a configured path.
-#. Build HTML from your module documentation: ``MODULES=mymodule make webdocs``.
-#. To build the HTML documentation for multiple modules, use a comma-separated list of module names: ``MODULES=mymodule,mymodule2 make webdocs``.
-#. View the HTML page at ``file:///path/to/docs/docsite/_build/html/modules/mymodule_module.html``.
+The community pages offer more information on :ref:`testing reStructuredText documentation <testing_documentation_locally>` if you extend the Ansible documentation with additional RST files.
 
 To ensure that your module documentation matches your ``argument_spec``:
 
@@ -41,4 +27,10 @@ To ensure that your module documentation matches your ``argument_spec``:
 
     ansible-test sanity --test validate-modules mymodule
 
+If you have Docker or Podman installed, you can also use them with the ``--docker`` option, which uses an image that already has all requirements installed:
+
+.. code-block:: bash
+
+    ansible-test sanity --docker --test validate-modules mymodule
+
 For other plugin types the steps are similar, just adjusting names and paths to the specific type.