Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

Ignore fenced examples in documentation link checks

pulse-triage[bot]b736d9eb24de
diff --git a/scripts/check_public_docs.py b/scripts/check_public_docs.py
index 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.py
index 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()