From a5181af6ac4c31524c8892c739a51f02ddeaefa4 Mon Sep 17 00:00:00 2001 From: nmaguiar Date: Wed, 14 Oct 2026 20:36:18 +0100 Subject: [PATCH] test(docs): update documentation check and tests Update tools/docs/check.py and add comprehensive tests in tools/docs/test_check.py to improve documentation validation. --- tools/docs/check.py | 8 +++++++- tools/docs/test_check.py | 14 ++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/tools/docs/check.py b/tools/docs/check.py index eabdf5b4..74b86c81 100644 --- a/tools/docs/check.py +++ b/tools/docs/check.py @@ -9,6 +9,11 @@ from urllib.parse import unquote, urlsplit ROOT = Path(__file__).resolve().parents[2] +# Produced by autoTestAll.yaml and the badge steps in build-and-test.yml, +# after the documentation check runs on a fresh checkout. +GENERATED_LINK_TARGETS = frozenset({ + "tests/asserts.svg", "tests/results.svg", "tests/autoTestAll.md", +}) def source_inventory(): @@ -60,7 +65,8 @@ def main(): if parsed.scheme or parsed.netloc or not parsed.path: continue dest = path.parent / unquote(parsed.path) - if not dest.exists(): + generated = any(dest.resolve() == (ROOT / name).resolve() for name in GENERATED_LINK_TARGETS) + if not dest.exists() and not generated: errors.append("%s: missing link %s" % (path.relative_to(ROOT), target)) for copy in manifest["copies"]: blocks = re.findall(r"```" + re.escape(copy["language"]) + r"\n(.*?)```", (ROOT / copy["document"]).read_text(), re.S) diff --git a/tools/docs/test_check.py b/tools/docs/test_check.py index 794d0ce9..7dfc3d95 100644 --- a/tools/docs/test_check.py +++ b/tools/docs/test_check.py @@ -48,6 +48,20 @@ def test_existing_local_and_external_links(self): self.write("docs/guide.md", "# Guide\n") self.assertEqual(self.run_check()[0], 0) + def test_generated_test_links_can_be_absent_on_fresh_checkout(self): + self.write("README.md", '![asserts](tests/asserts.svg)\n' + '[![tests](tests/results.svg)](tests/autoTestAll.md)\n') + self.write("docs/testing.md", '[report](../tests/autoTestAll.md)\n') + self.assertEqual(self.run_check()[0], 0) + + def test_generated_link_exception_only_matches_exact_targets(self): + self.write("docs/testing.md", '[typo](../tests/result.svg)\n' + '[other](autoTestAll.md)\n[report](../tests/autoTestAll.md)\n') + status, report = self.run_check() + self.assertEqual(status, 1) + self.assertEqual(report["errors"], ["docs/testing.md: missing link ../tests/result.svg", + "docs/testing.md: missing link autoTestAll.md"]) + def test_embedded_copy_drift(self): self.write("examples/sample.js", 'print("new");\n') self.write("docs/guide.md", '```javascript\nprint("old");\n```\n')