Debian Codegraph @

tests/doc/test_sphinx_gallery.py

raw
1 from __future__ import annotations
2
3 from collections import Counter
4 from pathlib import Path
5 import re
6 from typing import NamedTuple
7
8 import pytest
9
10 ROOT_DIR = str(Path(__file__).parent.parent.parent)
11 EXAMPLES_DIR = str(Path(ROOT_DIR) / 'examples')
12 PYVISTA_DIR = str(Path(ROOT_DIR) / 'pyvista')
13 DOC_DIR = str(Path(ROOT_DIR) / 'doc')
14
15
16 class _TestCaseTuple(NamedTuple):
17 test_id: str
18 file_path: str
19 has_crossref_to_api: bool
20 has_crossref_from_api: bool
21 anchor: str | None
22
23
24 def find_files_with_extension(root_dir: str, ext: str) -> list[str]:
25 """Return a list of files with the given extension under root_dir."""
26 return [str(p) for p in Path(root_dir).rglob(f'*{ext}')]
27
28
29 def count_ref_tags(py_root: str, rst_root: str) -> dict[str, int]:
30 """Count :ref:`...` targets in both .py and .rst files."""
31 pattern = re.compile(r':ref:`(?:[^<`]*<)?([^>`]+)>?`')
32 ref_counter = Counter()
33
34 # Process .py files
35 for file_path in find_files_with_extension(py_root, '.py'):
36 ref_counter.update(extract_ref_targets_from_file(file_path, pattern))
37
38 # Process .rst files
39 for file_path in find_files_with_extension(rst_root, '.rst'):
40 ref_counter.update(extract_ref_targets_from_file(file_path, pattern))
41
42 return dict(ref_counter)
43
44
45 def extract_ref_targets_from_file(file_path: str, pattern: re.Pattern) -> list[str]:
46 """Extract all :ref:`...` targets from a single file using the given pattern."""
47 with Path(file_path).open(encoding='utf-8') as f:
48 content = f.read()
49 return pattern.findall(content)
50
51
52 def analyze_gallery_example_file(file_path: str) -> tuple[bool, str]:
53 """Check a file for cross-references and return the first anchor."""
54 with Path(file_path).open(encoding='utf-8') as f:
55 content = f.read()
56
57 crossref_pattern = re.compile(r':(meth|func|class|mod|attr|exc|data|ref|obj):`[^`]+`')
58 anchor_pattern = re.compile(r'^\s*\.\.\s+_(.+?):\s*$', re.MULTILINE)
59
60 has_crossref = bool(crossref_pattern.search(content))
61 anchor_match = anchor_pattern.search(content)
62 anchor = anchor_match.group(1) if anchor_match else None
63
64 return has_crossref, anchor
65
66
67 def generate_test_cases() -> list[_TestCaseTuple]:
68 test_cases = []
69 example_files = find_files_with_extension(EXAMPLES_DIR, '.py')
70 ref_tags = count_ref_tags(py_root=PYVISTA_DIR, rst_root=DOC_DIR)
71 for file_path in example_files:
72 has_crossref_to_api, anchor = analyze_gallery_example_file(file_path)
73 has_crossref_from_api = bool(ref_tags.get(anchor, None))
74 test_id = str(Path(file_path).relative_to(ROOT_DIR))
75 test_cases.append(
76 _TestCaseTuple(
77 test_id=test_id,
78 file_path=file_path,
79 has_crossref_to_api=has_crossref_to_api,
80 has_crossref_from_api=has_crossref_from_api,
81 anchor=anchor,
82 )
83 )
84 return test_cases
85
86
87 TEST_CASES = generate_test_cases()
88 TEST_CASE_IDS = [case.test_id for case in TEST_CASES]
89
90
91 @pytest.mark.parametrize('test_case', TEST_CASES, ids=TEST_CASE_IDS)
92 def test_example_has_cross_reference_to_api(test_case):
93 if not test_case.has_crossref_to_api:
94 msg = (
95 "Example must include at least one cross-reference to PyVista's core or "
96 'plotting API.\n '
97 'E.g. if the example shows how to use `my_function`, then include a reference to '
98 '`my_function`.\n'
99 'E.g. use :class:`~pyvista.Plotter` to reference the `Plotter` class.\n'
100 'E.g. use :meth:`~pyvista.DataSetFilters.transform` to reference the '
101 '`transform` filter.\n'
102 )
103 pytest.fail(msg)
104
105
106 @pytest.mark.parametrize('test_case', TEST_CASES, ids=TEST_CASE_IDS)
107 def test_example_has_cross_reference_from_api(test_case):
108 if test_case.file_path.endswith('add_example.py'):
109 pytest.skip('This is a meta-example for dev purposes.')
110
111 if not test_case.has_crossref_from_api:
112 msg = (
113 "Example must include at least one cross-reference from PyVista's core or "
114 'plotting API.\n'
115 'E.g. if the example shows how to use `my_function` with dataset '
116 '`download_some_dataset`\n'
117 f'then consider including a reference:\n'
118 f' :ref:`{test_case.anchor}`\n'
119 f'in the docstring of `my_function` and/or `download_some_dataset`.'
120 )
121 pytest.fail(msg)
122
123
124 @pytest.mark.parametrize('test_case', TEST_CASES, ids=TEST_CASE_IDS)
125 def test_example_anchor(test_case):
126 def format_anchor(anchor):
127 return f'.. _{anchor}:'
128
129 expected_anchor = f'{Path(test_case.file_path).stem}_example'
130 if test_case.anchor is None:
131 msg = (
132 'Example is missing a reference anchor. Expected to find the anchor\n'
133 f'{format_anchor(expected_anchor)!r} at the top of the file.'
134 )
135 raise pytest.fail(msg)
136
137 if test_case.anchor != expected_anchor:
138 msg = (
139 f'Example has an incorrect reference anchor at the top of the file.\n'
140 f'Actual: {format_anchor(test_case.anchor)!r}\n'
141 f'Expected: {format_anchor(expected_anchor)!r}'
142 )
143 raise pytest.fail(msg)