check_markdown_links Namespace Reference

Functions
argparse.Namespace	parse_args ()
	Parse command-line arguments.
list[Path]|None	git_markdown (Path repo_root)
	List tracked plus non-ignored untracked Markdown files, so the scan set is reproducible for a given commit regardless of local build or scratch output.
	iter_markdown_files (Path repo_root, bool include_readme)
	Yield every repository Markdown file the current commit would carry.
bool	should_skip_link (str target)
	Perform should skip link.
str	normalize_target (str raw_target)
	Remove Markdown angle brackets, fragments, and query strings before resolving a link target.
int	main ()
	Entry point for this script.

Variables
	LINK_PATTERN = re.compile(r"!\[[^\]]*\]\‍(([^)\s]+)(?:\s+\"[^\"]*\")?\‍)|\[[^\]]*\]\‍(([^)\s]+)(?:\s+\"[^\"]*\")?\‍)")
dict	SKIP_DIRS = {".git", "docs_build", "obj", "bin", "stubs", "runs", "studies", "__pycache__", ".pytest_cache"}

Detailed Description

Local markdown link checker across every Markdown file the current commit carries.

Function Documentation

parse_args()

argparse.Namespace check_markdown_links.parse_args

(

)

Parse command-line arguments.

Returns

Value returned by parse_args().

Definition at line 19 of file check_markdown_links.py.

def parse_args() -> argparse.Namespace:
    """!
    @brief Parse command-line arguments.
    @return Value returned by `parse_args()`.
    """
    parser = argparse.ArgumentParser(
        description=(
            "Check local markdown links across every repository Markdown file.\n"
            "HTTP(S), mailto, and in-page anchor links are skipped."
        ),
        formatter_class=argparse.RawTextHelpFormatter,
        epilog=(
            "Examples:\n"
            "  python3 tests/tooling/check_markdown_links.py\n"
            "  python3 tests/tooling/check_markdown_links.py --repo-root .\n"
            "  python3 tests/tooling/check_markdown_links.py --no-readme"
        ),
    )
    parser.add_argument(
        "--repo-root",
        type=Path,
        default=Path(__file__).resolve().parents[2],
        help="Repository root directory (default: parent of this script).",
    )
    parser.add_argument(
        "--no-readme",
        action="store_true",
        help="Skip README.md in scan set.",
    )
    return parser.parse_args()
 
 

Here is the caller graph for this function:

git_markdown()

list[Path] | None check_markdown_links.git_markdown

(

Path

repo_root

)

List tracked plus non-ignored untracked Markdown files, so the scan set is reproducible for a given commit regardless of local build or scratch output.

Parameters

[in]

repo_root

Repository root directory.

Returns

Sorted Markdown paths, or None when git enumeration is unavailable.

Definition at line 54 of file check_markdown_links.py.

def git_markdown(repo_root: Path) -> list[Path] | None:
    """!
    @brief List tracked plus non-ignored untracked Markdown files, so the scan set is
           reproducible for a given commit regardless of local build or scratch output.
    @param[in] repo_root Repository root directory.
    @return Sorted Markdown paths, or None when git enumeration is unavailable.
    """
    return enumerate_repository_files(repo_root, ".md")
 
 

Here is the caller graph for this function:

iter_markdown_files()

check_markdown_links.iter_markdown_files	(	Path	repo_root,
		bool	include_readme
	)

Yield every repository Markdown file the current commit would carry.

Parameters

[in]	repo_root	Repository root directory.
[in]	include_readme	Whether the top-level README participates in the scan.

Returns

Generator of Markdown paths.

Definition at line 64 of file check_markdown_links.py.

def iter_markdown_files(repo_root: Path, include_readme: bool):
    """!
    @brief Yield every repository Markdown file the current commit would carry.
    @param[in] repo_root Repository root directory.
    @param[in] include_readme Whether the top-level README participates in the scan.
    @return Generator of Markdown paths.
    """
    candidates = git_markdown(repo_root)
    if candidates is None:
        # Fallback for a non-git export: walk the tree and skip generated/scratch trees.
        candidates = sorted(repo_root.rglob("*.md"))
    for markdown in candidates:
        if not markdown.is_file():
            continue
        parts = markdown.relative_to(repo_root).parts
        if SKIP_DIRS.intersection(parts):
            continue
        if not include_readme and markdown == repo_root / "README.md":
            continue
        yield markdown
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

should_skip_link()

bool check_markdown_links.should_skip_link

(

str

target

)

Perform should skip link.

Parameters

[in]

target

Argument passed to should_skip_link().

Returns

Value returned by should_skip_link().

Definition at line 86 of file check_markdown_links.py.

def should_skip_link(target: str) -> bool:
    """!
    @brief Perform should skip link.
    @param[in] target Argument passed to `should_skip_link()`.
    @return Value returned by `should_skip_link()`.
    """
    lower = target.lower()
    return (
        lower.startswith("http://")
        or lower.startswith("https://")
        or lower.startswith("mailto:")
        or lower.startswith("#")
    )
 
 

Here is the caller graph for this function:

normalize_target()

str check_markdown_links.normalize_target

(

str

raw_target

)

Remove Markdown angle brackets, fragments, and query strings before resolving a link target.

Parameters

[in]

raw_target

Argument passed to normalize_target().

Returns

Value returned by normalize_target().

Definition at line 101 of file check_markdown_links.py.

def normalize_target(raw_target: str) -> str:
    """!
    @brief Remove Markdown angle brackets, fragments, and query strings before resolving a link target.
    @param[in] raw_target Argument passed to `normalize_target()`.
    @return Value returned by `normalize_target()`.
    """
    cleaned = raw_target.strip().strip("<>").split("#", 1)[0].split("?", 1)[0]
    return cleaned
 
 

Here is the caller graph for this function:

main()

int check_markdown_links.main

(

)

Entry point for this script.

Returns

Value returned by main().

Definition at line 111 of file check_markdown_links.py.

def main() -> int:
    """!
    @brief Entry point for this script.
    @return Value returned by `main()`.
    """
    args = parse_args()
    repo_root = args.repo_root.resolve()
    failures = []
 
    scanned = list(iter_markdown_files(repo_root, include_readme=not args.no_readme))
    for md_file in scanned:
        if not md_file.is_file():
            failures.append((str(md_file), "<file>", "Markdown file not found"))
            continue
        content = md_file.read_text(encoding="utf-8", errors="replace")
        for match in LINK_PATTERN.findall(content):
            target = match[0] or match[1]
            if should_skip_link(target):
                continue
            normalized = normalize_target(target)
            if not normalized:
                continue
            resolved = (md_file.parent / normalized).resolve()
            try:
                exists = resolved.exists()
            except OSError as exc:
                failures.append((str(md_file.relative_to(repo_root)), target, f"{resolved} ({exc})"))
                continue
            if not exists:
                failures.append((str(md_file.relative_to(repo_root)), target, str(resolved)))
 
    if failures:
        print("Broken markdown links detected:")
        for src, target, resolved in failures:
            print(f"  - {src}: '{target}' -> missing '{resolved}'")
        return 1
 
    print(f"Markdown link check passed for {len(scanned)} repository Markdown files.")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

LINK_PATTERN

check_markdown_links.LINK_PATTERN = re.compile(r"!\[[^\]]*\]\‍(([^)\s]+)(?:\s+\"[^\"]*\")?\‍)|\[[^\]]*\]\‍(([^)\s]+)(?:\s+\"[^\"]*\")?\‍)")

Definition at line 16 of file check_markdown_links.py.

SKIP_DIRS

dict check_markdown_links.SKIP_DIRS = {".git", "docs_build", "obj", "bin", "stubs", "runs", "studies", "__pycache__", ".pytest_cache"}

Definition at line 51 of file check_markdown_links.py.