1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
:mod:`sphinx.ext.coverage` -- Collect doc coverage stats
========================================================
.. module:: sphinx.ext.coverage
:synopsis: Check Python modules and C API for coverage in the documentation.
.. role:: code-py(code)
:language: Python
This extension features one additional builder, the :class:`CoverageBuilder`.
.. todo:: Write this section.
.. 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: :code-py:`Sequence[str]`
:default: :code-py:`()`
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
coverage_ignore_functions
coverage_ignore_classes
coverage_ignore_pyobjects
:type: :code-py:`Sequence[str]`
:default: :code-py:`()`
List of `Python regular expressions`_.
If any of these regular expressions matches any part of the full import path
of a Python object, that Python object is excluded from the documentation
coverage report.
.. _Python regular expressions: https://docs.python.org/library/re
.. versionadded:: 2.1
.. confval:: coverage_c_path
:type: :code-py:`Sequence[str]`
:default: :code-py:`()`
.. confval:: coverage_c_regexes
:type: :code-py:`dict[str, str]`
:default: :code-py:`{}`
.. confval:: coverage_ignore_c_items
:type: :code-py:`dict[str, Sequence[str]]`
:default: :code-py:`{}`
.. confval:: coverage_write_headline
:type: :code-py:`bool`
:default: :code-py:`True`
Set to ``False`` to not write headlines.
.. versionadded:: 1.1
.. confval:: coverage_skip_undoc_in_source
:type: :code-py:`bool`
:default: :code-py:`False`
Skip objects that are not documented in the source with a docstring.
.. versionadded:: 1.1
.. confval:: coverage_show_missing_items
:type: :code-py:`bool`
:default: :code-py:`False`
Print objects that are missing to standard output also.
.. versionadded:: 3.1
.. confval:: coverage_statistics_to_report
:type: :code-py:`bool`
:default: :code-py:`True`
Print a tabular report of the coverage statistics to the coverage report.
Example output:
.. code-block:: text
+-----------------------+----------+--------------+
| Module | Coverage | Undocumented |
+=======================+==========+==============+
| package.foo_module | 100.00% | 0 |
+-----------------------+----------+--------------+
| package.bar_module | 83.33% | 1 |
+-----------------------+----------+--------------+
.. versionadded:: 7.2
.. confval:: coverage_statistics_to_stdout
:type: :code-py:`bool`
:default: :code-py:`False`
Print a tabular report of the coverage statistics to standard output.
Example output:
.. code-block:: text
+-----------------------+----------+--------------+
| Module | Coverage | Undocumented |
+=======================+==========+==============+
| package.foo_module | 100.00% | 0 |
+-----------------------+----------+--------------+
| package.bar_module | 83.33% | 1 |
+-----------------------+----------+--------------+
.. versionadded:: 7.2
|
