Merging upstream version 7.4.7.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 55 insertions, 6 deletions

diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst
index b9c493b..75ffc0f 100644
--- a/doc/usage/extensions/coverage.rst
+++ b/doc/usage/extensions/coverage.rst
@@ -6,15 +6,64 @@
 
 This extension features one additional builder, the :class:`CoverageBuilder`.
 
-.. class:: CoverageBuilder
+.. todo:: Write this section.
 
-   To use this builder, activate the coverage extension in your configuration
-   file and give ``-M coverage`` on the command line.
+.. note::
 
-.. todo:: Write this section.
+   The :doc:`sphinx-apidoc </man/sphinx-apidoc>` command can be used to
+   automatically generate API documentation for all code in a project,
+   avoiding the need to manually author these documents and keep them up-to-date.
+
+.. warning::
+
+   :mod:`~sphinx.ext.coverage` **imports** the modules to be documented.
+   If any modules have side effects on import,
+   these will be executed by the coverage builder when ``sphinx-build`` is run.
+
+   If you document scripts (as opposed to library modules),
+   make sure their main routine is protected by a
+   ``if __name__ == '__main__'`` condition.
+
+.. note::
+
+   For Sphinx (actually, the Python interpreter that executes Sphinx)
+   to find your module, it must be importable.
+   That means that the module or the package must be in
+   one of the directories on :data:`sys.path` -- adapt your :data:`sys.path`
+   in the configuration file accordingly.
+
+To use this builder, activate the coverage extension in your configuration file
+and run ``sphinx-build -M coverage`` on the command line.
+
+
+Builder
+-------
+
+.. py:class:: CoverageBuilder
+
+
+Configuration
+-------------
+
+Several configuration values can be used to specify
+what the builder should check:
+
+.. confval:: coverage_modules
+   :type: ``list[str]``
+   :default: ``[]``
+
+   List of Python packages or modules to test coverage for.
+   When this is provided, Sphinx will introspect each package
+   or module provided in this list as well
+   as all sub-packages and sub-modules found in each.
+   When this is not provided, Sphinx will only provide coverage
+   for Python packages and modules that it is aware of:
+   that is, any modules documented using the :rst:dir:`py:module` directive
+   provided in the :doc:`Python domain </usage/domains/python>`
+   or the :rst:dir:`automodule` directive provided by the
+   :mod:`~sphinx.ext.autodoc` extension.
 
-Several configuration values can be used to specify what the builder
-should check:
+   .. versionadded:: 7.4
 
 .. confval:: coverage_ignore_modules