Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Ignore fenced examples in documentation link checks
pulse-triage[bot]b736d9eb24de
diff --git a/scripts/check_public_docs.py b/scripts/check_public_docs.pyindex 67ca7a9095..c9453399ab 100644--- a/scripts/check_public_docs.py+++ b/scripts/check_public_docs.py@@ -31,6 +31,7 @@ CURRENT_PRODUCT_DOCS = (MARKDOWN_LINK = re.compile(r"!?\[[^\]]*\]\(([^)]+)\)")HTML_ASSET = re.compile(r"(?:src|href)=[\"']([^\"']+)[\"']")HEADING = re.compile(r"^#{1,6}\s+(.+?)\s*#*\s*$", re.MULTILINE)+FENCE_OPEN = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$")MISLEADING_PUBLIC_CLAIMS = {r"dead-man checks can notify when an expected external signal stops arriving": (@@ -68,8 +69,41 @@ def heading_slug(value: str) -> str:return re.sub(r"\s", "-", value).strip("-")+def outside_fenced_code(text: str) -> str:+ """Exclude fenced examples from heading and navigation-link checks.++ A shell comment is not a heading, and a Markdown example is not a live+ link. Respect the fence's character and minimum length, including an+ unclosed fence; blank lines keep adjacent prose from being joined.+ """++ content: list[str] = []+ closing: re.Pattern[str] | None = None+ for line in text.splitlines(keepends=True):+ value = line.rstrip("\r\n")+ if closing is not None:+ if closing.fullmatch(value):+ closing = None+ content.append("\n")+ continue++ opening = FENCE_OPEN.fullmatch(value)+ if opening is not None:+ fence, info = opening.groups()+ # Backticks in a backtick fence's info string make it ordinary+ # text, not the start of a code block.+ if fence[0] != "`" or "`" not in info:+ closing = re.compile(+ r" {0,3}" + re.escape(fence[0]) + "{" + str(len(fence)) + r",}[ \t]*"+ )+ content.append("\n")+ continue+ content.append(line)+ return "".join(content)++def anchors_for(path: Path) -> set[str]:- text = path.read_text(encoding="utf-8", errors="replace")+ text = outside_fenced_code(path.read_text(encoding="utf-8", errors="replace"))anchors: set[str] = set()counts: dict[str, int] = {}for heading in HEADING.findall(text):@@ -87,7 +121,7 @@ def check_links(files: list[Path]) -> list[str]:anchor_cache: dict[Path, set[str]] = {}for source in files:- text = source.read_text(encoding="utf-8", errors="replace")+ text = outside_fenced_code(source.read_text(encoding="utf-8", errors="replace"))targets = [match.group(1) for match in MARKDOWN_LINK.finditer(text)]targets.extend(match.group(1) for match in HTML_ASSET.finditer(text))diff --git a/scripts/tests/test_public_docs_claims.py b/scripts/tests/test_public_docs_claims.pyindex 3a71e549d6..a1409ba6b2 100644--- a/scripts/tests/test_public_docs_claims.py+++ b/scripts/tests/test_public_docs_claims.py@@ -155,6 +155,76 @@ class PublicDocsLinksTest(unittest.TestCase):self.assertEqual(errors, ["source.md: missing local target missing.md#one"])scan.assert_not_called()+ def test_code_comments_do_not_create_recovery_destinations_or_shift_suffixes(self) -> None:+ self.document(+ "guide.md", "# Recovery\n```sh\n# Recovery\n# Reset lockout\n```\n# Recovery\n",+ )+ source = self.document(+ "source.md", "[first](guide.md#recovery) [second](guide.md#recovery-1) "+ "[phantom](guide.md#recovery-2) [comment](guide.md#reset-lockout)\n",+ )++ self.assertEqual(public_docs.check_links([source]), [+ "source.md: missing anchor #recovery-2 in guide.md",+ "source.md: missing anchor #reset-lockout in guide.md",+ ])++ def test_fenced_markdown_and_html_examples_are_not_live_links(self) -> None:+ source = self.document(+ "source.md", "# Present\n```markdown\n[example](absent.md#one)\n"+ '<a href="also-absent.md#two">example</a>\n```\n'+ "~~~html\n<img src='absent.png'>\n~~~\n"+ "[real](#present) [broken](#missing)\n",+ )++ self.assertEqual(public_docs.check_links([source]), [+ "source.md: missing anchor #missing in source.md",+ ])++ def test_closing_fence_needs_matching_character_and_enough_markers(self) -> None:+ for opening, short, wrong, closing in [+ ("````sh", "```", "~~~~", "`````"),+ ("~~~~sh", "~~~", "````", "~~~~~"),+ ]:+ with self.subTest(opening=opening):+ guide = self.document(+ "guide.md", f"{opening}\n# Hidden\n{short}\n# Still hidden\n"+ f"{wrong}\n# Also hidden\n{closing}\n# Visible\n",+ )+ self.assertEqual(public_docs.anchors_for(guide), {"visible"})++ def test_closing_fence_cannot_carry_an_info_string(self) -> None:+ guide = self.document(+ "guide.md", "```sh\n# Hidden\n```not-a-close\n# Still hidden\n```\n# Visible\n",+ )+ self.assertEqual(public_docs.anchors_for(guide), {"visible"})++ def test_fences_allow_up_to_three_spaces_and_trailing_closing_whitespace(self) -> None:+ for indent in range(4):+ with self.subTest(indent=indent):+ guide = self.document(+ "guide.md", f"{' ' * indent}~~~sh\n# Hidden\n"+ f"{' ' * indent}~~~ \t\n# Visible\n",+ )+ self.assertEqual(public_docs.anchors_for(guide), {"visible"})++ def test_unclosed_fences_hide_examples_through_the_end_of_the_file(self) -> None:+ source = self.document(+ "source.md", "# Present\n```sh\n# Not a heading\n[example](absent.md)\n",+ )+ self.assertEqual(public_docs.anchors_for(source), {"present"})+ self.assertEqual(public_docs.check_links([source]), [])++ def test_backticks_in_backtick_info_do_not_open_a_fence(self) -> None:+ guide = self.document("guide.md", "```not`a-fence\n# Visible\n")+ self.assertEqual(public_docs.anchors_for(guide), {"visible"})++ def test_closed_example_does_not_join_prose_into_an_accidental_link(self) -> None:+ source = self.document(+ "source.md", "[example]\n```markdown\nanything\n```\n(absent.md)\n",+ )+ self.assertEqual(public_docs.check_links([source]), [])+if __name__ == "__main__":unittest.main()