Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /als-apg_osprey /tests /docs /test_directional_refs.py
| """Suite for the docs directional-reference guard. | |
| The guard exists because splitting a page turns "as described below" into a | |
| promise the page can no longer keep. A guard nobody has watched fail proves | |
| nothing, so the synthetic pages here pair one real offence with the lookalikes | |
| that have to stay quiet — a "below" pointing into this very page, a numeric | |
| comparison, an inline literal, a word inside a literal block, and a word one | |
| paragraph away — plus the two blind spots review found: a literal block opened | |
| inside a list item, and a Markdown page the guard cannot read. | |
| """ | |
| from __future__ import annotations | |
| import importlib.util | |
| from pathlib import Path | |
| import pytest | |
| _REPO_ROOT = Path(__file__).resolve().parents[2] | |
| _SCRIPT = _REPO_ROOT / "scripts" / "docs" / "check_directional_refs.py" | |
| OTHER_PAGE = """\ | |
| ===== | |
| Other | |
| ===== | |
| Other body text. | |
| """ | |
| # One offence — the first paragraph — and four lookalikes. | |
| GUIDE_PAGE = """\ | |
| ===== | |
| Guide | |
| ===== | |
| .. _guide-details: | |
| Details | |
| ======= | |
| The full story is below --- see :doc:`other`. | |
| Local pointer: the answer is below, in :ref:`guide-details`. | |
| A value above 30 runs last, as :doc:`other` explains. | |
| The ``above`` key is described in :doc:`other`. | |
| Verbatim text does not count, says :doc:`other`:: | |
| # the value above is only a default | |
| """ | |
| # A literal block opened inside a list item ends where the item's body ends, | |
| # not where the bullet does: the sentence after it is still prose. | |
| LIST_PAGE = """\ | |
| ===== | |
| Steps | |
| ===== | |
| 1. First do this:: | |
| run --it | |
| The answer is below, see :doc:`other`. | |
| """ | |
| # A blank line is a wall: the word belongs to its own paragraph, not the link's. | |
| PARAGRAPH_PAGE = """\ | |
| ========== | |
| Paragraphs | |
| ========== | |
| The answer is below. | |
| See :doc:`other` for the rest of the story. | |
| """ | |
| def _load_checker(): | |
| spec = importlib.util.spec_from_file_location("check_directional_refs", _SCRIPT) | |
| assert spec and spec.loader | |
| module = importlib.util.module_from_spec(spec) | |
| spec.loader.exec_module(module) | |
| return module | |
| checker = _load_checker() | |
| def _tree(root: Path, **pages: str) -> Path: | |
| """A throwaway ``docs/source`` holding *pages*, keyed by docname.""" | |
| docs_root = root / "docs" / "source" | |
| docs_root.mkdir(parents=True, exist_ok=True) | |
| for docname, body in pages.items(): | |
| (docs_root / f"{docname}.rst").write_text(body, encoding="utf-8") | |
| return docs_root | |
| def _findings(docs_root: Path, capsys) -> tuple[int, list[str]]: | |
| code = checker.main(["--docs-root", str(docs_root)]) | |
| out = capsys.readouterr().out | |
| return code, [line for line in out.splitlines() if line.strip() and "FAILED" not in line] | |
| def _line_of(page: str, text: str) -> int: | |
| return page.splitlines().index(text) + 1 | |
| # ── the offence, and the four lookalikes that must stay quiet ──────────── | |
| def test_a_cross_page_link_next_to_below_is_reported(tmp_path, capsys): | |
| docs_root = _tree(tmp_path, guide=GUIDE_PAGE, other=OTHER_PAGE) | |
| code, findings = _findings(docs_root, capsys) | |
| assert code == 1, "a cross-page :doc: next to 'below' must be reported" | |
| offence = _line_of(GUIDE_PAGE, "The full story is below --- see :doc:`other`.") | |
| assert findings == [f"source/guide.rst:{offence}: below near :doc:`other` (target on other)"], ( | |
| "exactly the one off-page 'below' must fire — a same-page :ref:, a numeric " | |
| "comparison, an inline literal and a literal block are not offences:\n" | |
| + "\n".join(findings) | |
| ) | |
| def test_a_same_page_target_is_not_an_offence(tmp_path, capsys): | |
| """Strip the cross-page paragraph and the page must go green.""" | |
| docs_root = _tree( | |
| tmp_path, | |
| guide=GUIDE_PAGE.replace("The full story is below --- see :doc:`other`.\n\n", ""), | |
| other=OTHER_PAGE, | |
| ) | |
| code, findings = _findings(docs_root, capsys) | |
| assert code == 0, "'below' next to a link into this very page is correct prose:\n" + "\n".join( | |
| findings | |
| ) | |
| def test_a_ref_no_label_explains_is_reported_as_unresolved(tmp_path, capsys): | |
| docs_root = _tree( | |
| tmp_path, | |
| guide=GUIDE_PAGE.replace(":ref:`guide-details`", ":ref:`no-such-label`"), | |
| other=OTHER_PAGE, | |
| ) | |
| code, findings = _findings(docs_root, capsys) | |
| assert code == 1, "a label the tree does not define must not pass silently" | |
| assert any("unresolved :ref:`no-such-label`" in line for line in findings), findings | |
| # ── the two blind spots review found ───────────────────────────────────── | |
| def test_a_literal_block_in_a_list_item_does_not_hide_the_rest_of_the_item(tmp_path, capsys): | |
| """The mask must end with the block, not with the whole list item.""" | |
| docs_root = _tree(tmp_path, steps=LIST_PAGE, other=OTHER_PAGE) | |
| code, findings = _findings(docs_root, capsys) | |
| assert code == 1, ( | |
| "prose that follows a literal block inside a list item is still prose — " | |
| "measuring the block from the bullet swallows it silently" | |
| ) | |
| offence = _line_of(LIST_PAGE, " The answer is below, see :doc:`other`.") | |
| assert findings == [f"source/steps.rst:{offence}: below near :doc:`other` (target on other)"], ( | |
| "\n".join(findings) | |
| ) | |
| def test_a_markdown_page_stops_the_run_instead_of_being_skipped(tmp_path): | |
| """MyST is enabled, so a Markdown page is legal — and unreadable here.""" | |
| docs_root = _tree(tmp_path, guide=GUIDE_PAGE, other=OTHER_PAGE) | |
| (docs_root / "notes.md").write_text("# Notes\n\n(anchor)=\n", encoding="utf-8") | |
| with pytest.raises(SystemExit) as raised: | |
| checker.check(docs_root) | |
| message = str(raised.value) | |
| assert "notes.md" in message and "Markdown" in message, message | |
| # ── the window is the paragraph, not a fixed span ──────────────────────── | |
| def test_a_directional_word_does_not_bleed_across_a_paragraph_break(tmp_path, capsys): | |
| docs_root = _tree(tmp_path, paragraphs=PARAGRAPH_PAGE, other=OTHER_PAGE) | |
| code, findings = _findings(docs_root, capsys) | |
| assert code == 0, ( | |
| "a blank line separates the word from the link; reporting across it is noise:\n" | |
| + "\n".join(findings) | |
| ) | |
| # ── the shipped tree ───────────────────────────────────────────────────── | |
| def test_the_shipped_docs_tree_is_clean(capsys): | |
| findings, summary = checker.check(_REPO_ROOT / "docs" / "source") | |
| assert findings == [], "directional wording next to an off-page link:\n" + "\n".join(findings) | |
| assert checker.main([]) == 0, "the default --docs-root must be the shipped tree" | |
| out = capsys.readouterr().out | |
| assert "roles checked" in out and "across 0 pages" not in out, ( | |
| f"the default run must actually read pages:\n{out}\n{summary}" | |
| ) | |
Xet Storage Details
- Size:
- 6.93 kB
- Xet hash:
- 30e69033196f9b91f1f26ba76cbe95df28b0cf99da263199f2f650ab7feddf63
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.