audit_page_types Namespace Reference

Functions
dict	declared_pages ()
	Every @page id in the documentation sources, with its file.
str	inline_type (Path path)
	The page type a page declares inline, if any.
int	main ()
	Fail when a published page is untyped or its declarations disagree.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]
str	REGISTRY = REPO_ROOT / "tests" / "tooling" / "page_types.json"
str	HTML_DIR = REPO_ROOT / "docs_build" / "html"
tuple	PAGE_DIRS = ("docs/pages", "docs")
dict	PLACEHOLDER_IDS = {"<ID>", "<id>"}

Detailed Description

Enforce that every published documentation page has a declared page type.

Function Documentation

declared_pages()

dict audit_page_types.declared_pages

(

)

Every @page id in the documentation sources, with its file.

Returns

Mapping of page id to source path.

Definition at line 20 of file audit_page_types.py.

def declared_pages() -> dict:
    """!
    @brief Every `@page` id in the documentation sources, with its file.
    @return Mapping of page id to source path.
    """
    pages: dict = {}
    for directory in PAGE_DIRS:
        for markdown in sorted((REPO_ROOT / directory).glob("*.md")):
            match = re.search(r"^@page\s+(\S+)", markdown.read_text(encoding="utf-8"), re.M)
            if match and match.group(1) not in PLACEHOLDER_IDS:
                pages.setdefault(match.group(1), markdown)
    return pages
 
 

Here is the caller graph for this function:

inline_type()

str audit_page_types.inline_type

(

Path

path

)

The page type a page declares inline, if any.

Parameters

[in]

path

Page source.

Returns

Declared type, or an empty string.

Definition at line 34 of file audit_page_types.py.

def inline_type(path: Path) -> str:
    """!
    @brief The page type a page declares inline, if any.
    @param[in] path Page source.
    @return Declared type, or an empty string.
    """
    match = re.search(r"@pagemeta\{([^,}]+)", path.read_text(encoding="utf-8"))
    return match.group(1).strip() if match else ""
 
 

Here is the caller graph for this function:

main()

int audit_page_types.main

(

)

Fail when a published page is untyped or its declarations disagree.

Coverage is enforced against the pages the build actually publishes. A central registry types all of them without adding repetitive chrome to each page; where a page also declares its type inline, the two must agree.

Returns

Process status code.

Definition at line 44 of file audit_page_types.py.

def main() -> int:
    """!
    @brief Fail when a published page is untyped or its declarations disagree.
 
    @details Coverage is enforced against the pages the build actually publishes. A
             central registry types all of them without adding repetitive chrome to each
             page; where a page also declares its type inline, the two must agree.
    @return Process status code.
    """
    registry = json.loads(REGISTRY.read_text(encoding="utf-8"))
    valid = set(registry["valid_types"])
    assignments = registry["assignments"]
    pages = declared_pages()
 
    published = {
        page_id for page_id in pages if (HTML_DIR / f"{page_id}.html").is_file()
    } or set(pages)
 
    problems: list = []
    for page_id in sorted(published):
        assigned = assignments.get(page_id)
        if not assigned:
            problems.append(f"{pages[page_id].name}: page '{page_id}' has no type assignment")
            continue
        if assigned not in valid:
            problems.append(f"{page_id}: type '{assigned}' is not one of {sorted(valid)}")
            continue
        declared = inline_type(pages[page_id])
        if declared and declared != assigned:
            problems.append(
                f"{pages[page_id].name}: inline @pagemeta says '{declared}' but the registry "
                f"says '{assigned}'"
            )
    for stale in sorted(set(assignments) - set(pages)):
        problems.append(f"registry assigns a type to '{stale}', which is not a declared page")
 
    if problems:
        print("Page-type coverage violations:", file=sys.stderr)
        for problem in problems:
            print(f"  {problem}", file=sys.stderr)
        print(
            "\nAssign a type in tests/tooling/page_types.json. See 63_Page_Type_Contract for\n"
            "what each type owes the reader.",
            file=sys.stderr,
        )
        return 1
 
    from collections import Counter
    spread = Counter(assignments[p] for p in published)
    summary = ", ".join(f"{count} {kind}" for kind, count in sorted(spread.items()))
    print(f"Page-type audit passed: {len(published)} published pages typed ({summary}).")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

REPO_ROOT

audit_page_types.REPO_ROOT = Path(__file__).resolve().parents[2]

Definition at line 12 of file audit_page_types.py.

REGISTRY

str audit_page_types.REGISTRY = REPO_ROOT / "tests" / "tooling" / "page_types.json"

Definition at line 13 of file audit_page_types.py.

HTML_DIR

str audit_page_types.HTML_DIR = REPO_ROOT / "docs_build" / "html"

Definition at line 14 of file audit_page_types.py.

PAGE_DIRS

tuple audit_page_types.PAGE_DIRS = ("docs/pages", "docs")

Definition at line 15 of file audit_page_types.py.

PLACEHOLDER_IDS

dict audit_page_types.PLACEHOLDER_IDS = {"<ID>", "<id>"}

Definition at line 17 of file audit_page_types.py.