Skip to content

test relative links in example documentation #1811

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
KristofersJurevics wants to merge 1 commit into
base: main
Choose a base branch
from
+45 −0
Open

test relative links in example documentation #1811

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions docs/test_example_links.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
"""Check that links in the example documentation point at real files."""

@ajbozarth ajbozarth Nov 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CI won't collect this file. The pytest step in .github/workflows/quality.yml runs only test and tooling/docs-autogen/test_validate.py, so a test in docs/ only ever runs locally. Could you move it to test/test_example_links.py, next to test/test_example_collection.py? It will then run in CI and pick up the auto-applied unit marker. test/ files also need the SPDX license header; the hook excludes docs/, which is why it passes now. Update EXAMPLES_ROOT / REPOSITORY_ROOT for the new location.


from __future__ import annotations

import re
from pathlib import Path
from urllib.parse import urlsplit

@ajbozarth ajbozarth Nov 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Paired with the unquote suggestion below:

Suggested change
from urllib.parse import urlsplit
from urllib.parse import unquote, urlsplit


EXAMPLES_ROOT = Path(__file__).parent / "examples"
REPOSITORY_ROOT = EXAMPLES_ROOT.parent.parent

# The CLI page is generated during the documentation build and intentionally is not
# checked into the repository.
GENERATED_DOCS = {REPOSITORY_ROOT / "docs" / "docs" / "reference" / "cli.md"}
LINK_RE = re.compile(r"!?\[[^\]]*\]\(\s*(?:<([^>]+)>|([^\s)]+))")


def _local_links(path: Path):
in_code_block = False
for line in path.read_text(encoding="utf-8").splitlines():
if line.strip().startswith("```"):
in_code_block = not in_code_block
continue
if in_code_block:
continue
yield from (first or second for first, second in LINK_RE.findall(line))
Comment on lines +21 to +26

@ajbozarth ajbozarth Nov 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two parsing cases cause false positives: links inside inline code (`[x](missing.md)` gets flagged) and ~~~ fences (not treated as code blocks).

Suggested change
if line.strip().startswith("```"):
in_code_block = not in_code_block
continue
if in_code_block:
continue
yield from (first or second for first, second in LINK_RE.findall(line))
if line.strip().startswith(("```", "~~~")):
in_code_block = not in_code_block
continue
if in_code_block:
continue
line = re.sub(r"`[^`]*`", "", line)
yield from (first or second for first, second in LINK_RE.findall(line))



def _missing_links() -> list[str]:
missing = []
for markdown_file in EXAMPLES_ROOT.rglob("*.md"):
for target in _local_links(markdown_file):
parsed = urlsplit(target)
if parsed.scheme or parsed.netloc:
continue
target_path = (markdown_file.parent / parsed.path).resolve()

@ajbozarth ajbozarth Nov 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

URL-encoded links like [x](my%20file.md) are reported as missing even when the file exists, so the path should be unquoted first:

Suggested change
target_path = (markdown_file.parent / parsed.path).resolve()
target_path = (markdown_file.parent / unquote(parsed.path)).resolve()

if target_path.exists() or target_path in GENERATED_DOCS:
continue
missing.append(f"{markdown_file.relative_to(REPOSITORY_ROOT)}: {target}")
return missing


def test_example_markdown_links_resolve():

@ajbozarth ajbozarth Nov 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This only checks the current tree, which has no broken links, so nothing shows the check can actually fail. Could you add a couple of tmp_path tests that point _missing_links at a fixture directory (one broken link, one valid link with an anchor, one in a code block)? tooling/docs-autogen/test_validate.py has examples of this pattern. Making _missing_links take the root as a parameter would make that easy.

"""Prevent broken relative links from being added outside Docusaurus."""
assert not (missing := _missing_links()), "Broken example links:\n" + "\n".join(missing)
Loading