| 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) |