20261014-195037

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)

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