IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Allow explicitly specifying modules in the coverage builder (#11592)

Browse Source 
Currently there is no mechanism to identify totally undocumented modules
in the coverage builder, unlike with partially documented modules.
Resolve this by introducing a new ``coverage_modules`` config option.
This is a list of modules that should be documented somewhere
within the documentation tree. 
Any modules that are specified in the configuration value but 
are not documented anywhere will result in a warning. 
Likewise, any modules that are not in the config option but 
are documented somewhere will result in a warning.

Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane
2024-07-11 07:36:36 +01:00
committed by GitHub
parent 3d118ce81c
commit 6b37a6b2a2
10 changed files with 207 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
doc/usage/extensions/coverage.rst
View File

@@ -6,15 +6,64 @@
This extension features one additional builder, the :class:`CoverageBuilder`.
.. class:: CoverageBuilder
To use this builder, activate the coverage extension in your configuration
file and give ``-M coverage`` on the command line.
.. todo:: Write this section.
Several configuration values can be used to specify what the builder
should check:
.. note::
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.
.. versionadded:: 7.4
.. confval:: coverage_ignore_modules