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
|
"""Test the coverage builder."""
from __future__ import annotations
import pickle
from typing import TYPE_CHECKING
import pytest
if TYPE_CHECKING:
from sphinx.testing.util import SphinxTestApp
@pytest.mark.sphinx('coverage', testroot='root')
def test_build(app: SphinxTestApp) -> None:
app.build(force_all=True)
py_undoc = (app.outdir / 'python.txt').read_text(encoding='utf8')
assert py_undoc.startswith(
'Undocumented Python objects\n===========================\n',
)
assert 'autodoc_target\n--------------\n' in py_undoc
assert ' * Class -- missing methods:\n' in py_undoc
assert ' * raises\n' in py_undoc
# these two are documented in autodoc.txt
assert ' * function\n' not in py_undoc
assert ' * Class\n' not in py_undoc
# in the "failed import" section
assert " * mod -- No module named 'mod'" in py_undoc
assert 'undocumented py' not in app.status.getvalue()
c_undoc = (app.outdir / 'c.txt').read_text(encoding='utf8')
assert c_undoc.startswith(
'Undocumented C API elements\n===========================\n',
)
assert 'api.h' in c_undoc
assert ' * Py_SphinxTest' in c_undoc
undoc_py, undoc_c, py_undocumented, py_documented = pickle.loads(
(app.outdir / 'undoc.pickle').read_bytes()
)
assert len(undoc_c) == 1
# the key is the full path to the header file, which isn't testable
assert next(iter(undoc_c.values())) == {('function', 'Py_SphinxTest')}
assert 'autodoc_target' in undoc_py
assert 'funcs' in undoc_py['autodoc_target']
assert 'raises' in undoc_py['autodoc_target']['funcs']
assert 'classes' in undoc_py['autodoc_target']
assert 'Class' in undoc_py['autodoc_target']['classes']
assert 'undocmeth' in undoc_py['autodoc_target']['classes']['Class']
assert 'undocumented c' not in app.status.getvalue()
@pytest.mark.sphinx('coverage', testroot='ext-coverage')
def test_coverage_ignore_pyobjects(app: SphinxTestApp) -> None:
app.build(force_all=True)
actual = (app.outdir / 'python.txt').read_text(encoding='utf8')
expected = """\
Undocumented Python objects
===========================
Statistics
----------
+---------------------------+----------+--------------+
| Module | Coverage | Undocumented |
+===========================+==========+==============+
| grog | 100.00% | 0 |
+---------------------------+----------+--------------+
| grog.coverage_missing | 100.00% | 0 |
+---------------------------+----------+--------------+
| grog.coverage_not_ignored | 0.00% | 2 |
+---------------------------+----------+--------------+
| TOTAL | 0.00% | 2 |
+---------------------------+----------+--------------+
grog.coverage_missing
---------------------
Classes:
* Missing
grog.coverage_not_ignored
-------------------------
Classes:
* Documented -- missing methods:
- not_ignored1
- not_ignored2
* NotIgnored
"""
assert actual == expected
@pytest.mark.sphinx(
'coverage', testroot='root', confoverrides={'coverage_show_missing_items': True}
)
def test_show_missing_items(app: SphinxTestApp) -> None:
app.build(force_all=True)
assert 'undocumented' in app.status.getvalue()
assert 'py function raises' in app.status.getvalue()
assert 'py class Base' in app.status.getvalue()
assert 'py method Class.roger' in app.status.getvalue()
assert 'c api Py_SphinxTest [ function]' in app.status.getvalue()
@pytest.mark.sphinx(
'coverage', testroot='root', confoverrides={'coverage_show_missing_items': True}
)
def test_show_missing_items_quiet(app: SphinxTestApp) -> None:
app.quiet = True
app.build(force_all=True)
assert (
'undocumented python function: autodoc_target :: raises'
) in app.warning.getvalue()
assert 'undocumented python class: autodoc_target :: Base' in app.warning.getvalue()
assert (
'undocumented python method: autodoc_target :: Class :: roger'
) in app.warning.getvalue()
assert 'undocumented c api: Py_SphinxTest [function]' in app.warning.getvalue()
|
