Skip to content

scripts.check_docs_coverage

Fail when source symbols or public explanations disappear from the docs.

View the complete module source at #L1-L187.

API details

Each callable below includes its exact signature, type annotations, inputs, defaults, return contract, documented exceptions, implementation source, and parsed docstring sections when the source provides them.

scripts.check_docs_coverage

Fail when source symbols or public explanations disappear from the docs.

scripts.check_docs_coverage.main 

main() -> int

Validate module coverage, symbol coverage, and public docstring coverage.

Source code in scripts/check_docs_coverage.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
def main() -> int:
    """Validate module coverage, symbol coverage, and public docstring coverage."""

    modules = build_inventory()
    symbols = [symbol for module in modules for symbol in module.symbols]
    repository_modules = build_repository_inventory()
    repository_symbols = [
        symbol for module in repository_modules for symbol in module.symbols
    ]
    page_paths = [module.page_path for module in repository_modules]
    runtime_page_paths = [module.page_path for module in modules]
    cli_options = build_cli_inventory()
    cli_reference = render_cli_reference(cli_options)

    issues: list[str] = []
    if len(page_paths) != len(set(page_paths)):
        issues.append("Generated API page paths are not unique.")
    if not cli_options:
        issues.append("No argparse options were discovered.")
    mkdocs_config = (REPOSITORY_ROOT / "mkdocs.yml").read_text(encoding="utf-8")
    navigable_runtime_pages = sum(
        page_path in mkdocs_config for page_path in runtime_page_paths
    )
    if navigable_runtime_pages != len(runtime_page_paths):
        issues.append(
            "Runtime module navigation is incomplete: "
            f"{navigable_runtime_pages}/{len(runtime_page_paths)} pages."
        )
    for option in cli_options:
        if option.source_url not in cli_reference:
            issues.append(
                f"CLI option missing from generated reference: {option.path}:{option.line}"
            )

    for module in modules:
        if not module.docstring:
            issues.append(f"Missing module docstring: {module.path}")
        for symbol in module.symbols:
            if symbol.addressable and symbol.public and not symbol.documented:
                issues.append(
                    f"Missing public docstring: {module.path}:{symbol.line} "
                    f"({symbol.qualname})"
                )

    docs_dir = REPOSITORY_ROOT / "docs"
    markdown_pages = sorted(docs_dir.rglob("*.md"))
    generated_marker = "<!-- Generated by scripts/gen_api_reference.py."
    hand_written_pages = []
    for page in markdown_pages:
        content = page.read_text(encoding="utf-8")
        if not content.startswith(generated_marker):
            hand_written_pages.append(page)
        if not (
            any(line.startswith("# ") for line in content.splitlines())
            or "<h1" in content.lower()
        ):
            issues.append(f"Missing H1 heading: {page.relative_to(REPOSITORY_ROOT)}")

    http_reference = docs_dir / "reference" / "http-api.md"
    http_content = http_reference.read_text(encoding="utf-8")
    server_module = next(
        module for module in modules if module.name == "vllm_mlx.server"
    )
    server_symbols = {symbol.qualname: symbol for symbol in server_module.symbols}
    server_tree = ast.parse(
        (REPOSITORY_ROOT / server_module.path).read_text(encoding="utf-8")
    )
    route_count = 0
    for node in ast.walk(server_tree):
        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            continue
        for decorator in node.decorator_list:
            if not (
                isinstance(decorator, ast.Call)
                and isinstance(decorator.func, ast.Attribute)
                and isinstance(decorator.func.value, ast.Name)
                and decorator.func.value.id == "app"
                and decorator.func.attr in {"get", "post", "put", "patch", "delete"}
            ):
                continue
            route_count += 1
            route_path = ast.literal_eval(decorator.args[0])
            symbol = server_symbols[node.name]
            if f"`{decorator.func.attr.upper()}`" not in http_content:
                issues.append(f"HTTP method missing from reference: {node.name}")
            if f"`{route_path}`" not in http_content:
                issues.append(f"HTTP route missing from reference: {route_path}")
            if symbol.source_url not in http_content:
                issues.append(
                    f"HTTP source link is stale or missing: {node.name} "
                    f"({symbol.source_url})"
                )

    required_paths = [
        REPOSITORY_ROOT / "mkdocs.yml",
        docs_dir / "llms.txt",
        docs_dir / "reference" / "python-symbols.md",
        docs_dir / "development" / "agent-guide.md",
        REPOSITORY_ROOT / ".github" / "workflows" / "docs.yml",
    ]
    for path in required_paths:
        if not path.exists():
            issues.append(
                f"Missing documentation artifact: {path.relative_to(REPOSITORY_ROOT)}"
            )

    public_symbols = [
        symbol for symbol in symbols if symbol.addressable and symbol.public
    ]
    documented_public = [symbol for symbol in public_symbols if symbol.documented]
    explained_symbols = [symbol for symbol in repository_symbols if symbol.summary]
    runtime_parameters = [
        parameter for symbol in symbols for parameter in symbol.parameters
    ]
    unexplained_parameters = [
        parameter for parameter in runtime_parameters if not parameter.description
    ]
    if unexplained_parameters:
        issues.append(
            f"Callable parameters missing explanations: {len(unexplained_parameters)}"
        )
    symbol_index = (docs_dir / "reference" / "python-symbols.md").read_text(
        encoding="utf-8"
    )
    indexed_symbols = symbol_index.count("data-api-symbol data-symbol-kind=")
    if indexed_symbols != len(symbols):
        issues.append(
            "Python symbol index is incomplete: "
            f"{indexed_symbols}/{len(symbols)} entries."
        )
    print(f"Module reference coverage: {len(modules)}/{len(modules)} (100.0%)")
    print(
        "Navigable runtime module pages: "
        f"{navigable_runtime_pages}/{len(runtime_page_paths)} (100.0%)"
    )
    print(f"Symbol source-map coverage: {len(symbols)}/{len(symbols)} (100.0%)")
    print(f"Searchable symbol index: {indexed_symbols}/{len(symbols)} (100.0%)")
    print(
        "Callable input parameter records: "
        f"{len(runtime_parameters)}/{len(runtime_parameters)} (100.0%)"
    )
    print(
        "Public symbol explanations: "
        f"{len(documented_public)}/{len(public_symbols)} "
        f"({len(documented_public) / max(len(public_symbols), 1):.1%})"
    )
    print(
        "All symbol reference explanations: "
        f"{len(explained_symbols)}/{len(repository_symbols)} "
        f"({len(explained_symbols) / max(len(repository_symbols), 1):.1%})"
    )
    print(
        "Repository source-module coverage: "
        f"{len(repository_modules)}/{len(repository_modules)} (100.0%)"
    )
    print(f"Hand-written Markdown pages: {len(hand_written_pages)}")
    print(f"HTTP endpoint reference coverage: {route_count}/{route_count} (100.0%)")
    print(
        f"CLI option reference coverage: {len(cli_options)}/{len(cli_options)} (100.0%)"
    )

    if issues:
        print("\nDocumentation coverage failures:", file=sys.stderr)
        for issue in issues:
            print(f"- {issue}", file=sys.stderr)
        return 1
    return 0

Complete contract reference

Expand any definition for its exact inputs, annotations, defaults, return contract, directly raised exceptions, source-grounded behavior, and immutable line link. This section includes private and nested definitions that ordinary API generators omit.

scripts.check_docs_coverage.main · function 
scripts.check_docs_coverage.main() -> int

Validate module coverage, symbol coverage, and public docstring coverage.

Parameters

This callable has no explicit inputs.

Returns

  • Type: int
  • Direct return expressions: 1; 0

Exceptions and behavior

Function main calls build_inventory, build_repository_inventory, build_cli_inventory, render_cli_reference; has 2 explicit return paths. No direct raise statement appears in this definition.

View source #L17-L183.

Complete symbol map

This map also includes private definitions and nested helpers. The signature column exposes every explicit input even when an internal helper has no dedicated parameter prose.

Symbol Kind Signature and inputs What it does Source
main function main() -> int Validate module coverage, symbol coverage, and public docstring coverage. #L17-L183