From a4cb511c64f141016f6f217740d37a98894aa576 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 20 Feb 2024 13:46:12 +0100 Subject: [PATCH] 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. --- docs/docsite/Makefile | 18 ++------------ .../community/documentation_contributions.rst | 16 +++++-------- .../rst/dev_guide/testing_documentation.rst | 24 +++++++------------ 3 files changed, 16 insertions(+), 42 deletions(-) diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile index 93e8fba044c..afcfe4bab7f 100644 --- a/docs/docsite/Makefile +++ b/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) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 05657287b68..a29b8c537f2 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/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: diff --git a/docs/docsite/rst/dev_guide/testing_documentation.rst b/docs/docsite/rst/dev_guide/testing_documentation.rst index 280e2c03270..65cfc0ce84e 100644 --- a/docs/docsite/rst/dev_guide/testing_documentation.rst +++ b/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 `` 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 `. +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 `. -#. 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 ` 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.