Skip to content

scripts.mkdocs_hooks

MkDocs hooks that publish machine-readable documentation artifacts.

View the complete module source at #L1-L225.

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.mkdocs_hooks

MkDocs hooks that publish machine-readable documentation artifacts.

scripts.mkdocs_hooks.SOURCE_BRANCH_URL module-attribute 

SOURCE_BRANCH_URL = 'https://github.com/waybarrios/vllm-mlx/blob/gh-pages/'

scripts.mkdocs_hooks._source_revision cached 

_source_revision() -> str

Return the immutable commit represented by this documentation build.

Source code in scripts/mkdocs_hooks.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
@lru_cache(maxsize=1)
def _source_revision() -> str:
    """Return the immutable commit represented by this documentation build."""

    for candidate in (
        os.environ.get("VLLM_MLX_DOCS_SOURCE_REVISION", ""),
        os.environ.get("GITHUB_SHA", ""),
    ):
        if re.fullmatch(r"[0-9a-fA-F]{40}", candidate):
            return candidate.lower()
    completed = subprocess.run(
        ["git", "rev-parse", "HEAD"],
        cwd=REPOSITORY_ROOT,
        check=True,
        capture_output=True,
        text=True,
    )
    revision = completed.stdout.strip()
    if not re.fullmatch(r"[0-9a-f]{40}", revision):
        raise ValueError(f"Expected an immutable Git commit, received {revision!r}")
    return revision

_pin_source_links(text: str, revision: str) -> str

Replace mutable gh-pages source links with one commit permalink.

Source code in scripts/mkdocs_hooks.py 
49
50
51
52
53
54
55
def _pin_source_links(text: str, revision: str) -> str:
    """Replace mutable gh-pages source links with one commit permalink."""

    return text.replace(
        SOURCE_BRANCH_URL,
        f"https://github.com/waybarrios/vllm-mlx/blob/{revision}/",
    )

scripts.mkdocs_hooks.on_page_markdown 

on_page_markdown(markdown: str, **kwargs) -> str

Pin every rendered GitHub source link to the build commit.

Source code in scripts/mkdocs_hooks.py 
58
59
60
61
62
def on_page_markdown(markdown: str, **kwargs) -> str:
    """Pin every rendered GitHub source link to the build commit."""

    del kwargs
    return _pin_source_links(markdown, _source_revision())

scripts.mkdocs_hooks.on_post_page 

on_post_page(output: str, page=None, **kwargs) -> str

Normalize search alternates and localized homepage presentation.

Source code in scripts/mkdocs_hooks.py 
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
def on_post_page(output: str, page=None, **kwargs) -> str:
    """Normalize search alternates and localized homepage presentation."""

    del kwargs
    canonical_url = getattr(page, "canonical_url", "")
    if canonical_url:
        output = re.sub(
            r'(<link\s+rel="alternate"\s+href=")([^"]+)'
            r'("\s+hreflang="[^"]+"\s*/?>)',
            lambda match: (
                f"{match.group(1)}"
                f"{urljoin(canonical_url, match.group(2))}"
                f"{match.group(3)}"
            ),
            output,
        )
    if 'class="vllm-hero"' not in output:
        return output
    return re.sub(
        r"\s*<a\b(?=[^>]*\brel=\"edit\")[^>]*>.*?</a>",
        "",
        output,
        count=1,
        flags=re.DOTALL,
    )

scripts.mkdocs_hooks._markdown_documents 

_markdown_documents() -> list[Path]

Return tracked hand-written documentation pages in stable order.

Source code in scripts/mkdocs_hooks.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def _markdown_documents() -> list[Path]:
    """Return tracked hand-written documentation pages in stable order."""

    return sorted(
        path
        for path in (REPOSITORY_ROOT / "docs").rglob("*.md")
        if not path.read_text(encoding="utf-8").startswith(
            "<!-- Generated by scripts/gen_api_reference.py."
        )
    )

scripts.mkdocs_hooks.on_post_build 

on_post_build(config, **kwargs) -> None

Write Markdown mirrors, the API inventory, and the full LLM corpus.

Source code in scripts/mkdocs_hooks.py 
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
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
def on_post_build(config, **kwargs) -> None:
    """Write Markdown mirrors, the API inventory, and the full LLM corpus."""

    del kwargs
    site_dir = Path(config["site_dir"])
    docs_dir = REPOSITORY_ROOT / "docs"
    inventory = build_inventory()
    repository_inventory = build_repository_inventory()
    cli_inventory = build_cli_inventory()
    source_revision = _source_revision()

    full_parts = [
        "# vllm-mlx complete documentation",
        "",
        "> Complete human-authored documentation and static Python API inventory. "
        "Use `/llms.txt` for a compact index.",
        "",
    ]

    for source_path in _markdown_documents():
        relative = source_path.relative_to(docs_dir)
        content = _pin_source_links(
            source_path.read_text(encoding="utf-8").strip(), source_revision
        )
        mirror_path = site_dir / relative
        mirror_path.parent.mkdir(parents=True, exist_ok=True)
        mirror_path.write_text(content + "\n", encoding="utf-8")
        full_parts.extend(
            [
                f"# Documentation page: `{relative.as_posix()}`",
                "",
                content,
                "",
            ]
        )

    for module in repository_inventory:
        mirror_path = site_dir / module.page_path
        mirror_path.parent.mkdir(parents=True, exist_ok=True)
        mirror_path.write_text(
            _pin_source_links(render_module_page(module), source_revision),
            encoding="utf-8",
        )
        full_parts.extend(
            [_pin_source_links(render_module_for_llms(module), source_revision), ""]
        )

    symbol_index_source = docs_dir / "reference" / "python-symbols.md"
    symbol_index_mirror = site_dir / "reference" / "python-symbols.md"
    symbol_index_mirror.parent.mkdir(parents=True, exist_ok=True)
    symbol_index_mirror.write_text(
        _pin_source_links(
            symbol_index_source.read_text(encoding="utf-8"), source_revision
        ),
        encoding="utf-8",
    )

    cli_markdown = _pin_source_links(
        render_cli_reference(cli_inventory), source_revision
    )
    cli_mirror = site_dir / "reference" / "cli-options.md"
    cli_mirror.parent.mkdir(parents=True, exist_ok=True)
    cli_mirror.write_text(cli_markdown, encoding="utf-8")
    full_parts.extend([cli_markdown, ""])

    inventory_payload = {
        "schema_version": "1.0",
        "repository": "waybarrios/vllm-mlx",
        "source_branch": "gh-pages",
        "source_revision": source_revision,
        "module_count": len(inventory),
        "symbol_count": sum(len(module.symbols) for module in inventory),
        "modules": [module.to_dict() for module in inventory],
    }
    (site_dir / "api-inventory.json").write_text(
        _pin_source_links(
            json.dumps(inventory_payload, indent=2, ensure_ascii=False),
            source_revision,
        )
        + "\n",
        encoding="utf-8",
    )
    source_inventory_payload = {
        "schema_version": "1.0",
        "repository": "waybarrios/vllm-mlx",
        "source_branch": "gh-pages",
        "source_revision": source_revision,
        "module_count": len(repository_inventory),
        "symbol_count": sum(len(module.symbols) for module in repository_inventory),
        "source_roots": ["vllm_mlx", "scripts", "examples"],
        "modules": [module.to_dict() for module in repository_inventory],
    }
    (site_dir / "source-inventory.json").write_text(
        _pin_source_links(
            json.dumps(source_inventory_payload, indent=2, ensure_ascii=False),
            source_revision,
        )
        + "\n",
        encoding="utf-8",
    )
    (site_dir / "cli-inventory.json").write_text(
        _pin_source_links(
            json.dumps(
                {
                    "schema_version": "1.0",
                    "repository": "waybarrios/vllm-mlx",
                    "source_branch": "gh-pages",
                    "source_revision": source_revision,
                    "option_count": len(cli_inventory),
                    "options": [option.to_dict() for option in cli_inventory],
                },
                indent=2,
                ensure_ascii=False,
            ),
            source_revision,
        )
        + "\n",
        encoding="utf-8",
    )
    (site_dir / "llms-full.txt").write_text(
        "\n".join(full_parts).rstrip() + "\n", encoding="utf-8"
    )

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.mkdocs_hooks._source_revision · function 
scripts.mkdocs_hooks._source_revision() -> str

Return the immutable commit represented by this documentation build.

Parameters

This callable has no explicit inputs.

Returns

  • Type: str
  • Direct return expressions: candidate.lower(); revision

Exceptions and behavior

Function _source_revision calls os.environ.get, re.fullmatch, candidate.lower, subprocess.run; can raise ValueError; has 2 explicit return paths. Directly raised exceptions: ValueError.

View source #L27-L46.

scripts.mkdocs_hooks.on_page_markdown · function 
scripts.mkdocs_hooks.on_page_markdown(markdown: str, **kwargs) -> str

Pin every rendered GitHub source link to the build commit.

Parameters

Name Type Required Default Description
markdown str yes none Required positional or keyword input.
**kwargs not annotated no none Additional variadic keyword inputs accepted by this callable.

Returns

  • Type: str
  • Direct return expressions: _pin_source_links(markdown, _source_revision())

Exceptions and behavior

Function on_page_markdown calls _pin_source_links, _source_revision; returns _pin_source_links(markdown, _source_revision()). No direct raise statement appears in this definition.

View source #L58-L62.

scripts.mkdocs_hooks.on_post_page · function 
scripts.mkdocs_hooks.on_post_page(output: str, page = None, **kwargs) -> str

Normalize search alternates and localized homepage presentation.

Parameters

Name Type Required Default Description
output str yes none Required positional or keyword input.
page not annotated no None Optional positional or keyword input; defaults to None.
**kwargs not annotated no none Additional variadic keyword inputs accepted by this callable.

Returns

  • Type: str
  • Direct return expressions: output; re.sub('\\s*<a\\b(?=[^>]*\\brel=\\"edit\\")[^>]*>.*?</a>', '', output, count=1, flags=re.DOTALL)

Exceptions and behavior

Function on_post_page calls getattr, re.sub; has 2 explicit return paths. No direct raise statement appears in this definition.

View source #L65-L89.

scripts.mkdocs_hooks._markdown_documents · function 
scripts.mkdocs_hooks._markdown_documents() -> list[Path]

Return tracked hand-written documentation pages in stable order.

Parameters

This callable has no explicit inputs.

Returns

  • Type: list[Path]
  • Direct return expressions: sorted((path for path in (REPOSITORY_ROOT / 'docs').rglob('*.md') if not path.read_text(encoding='utf-8').startswith('<…

Exceptions and behavior

Function _markdown_documents calls sorted, (REPOSITORY_ROOT / 'docs').rglob, path.read_text(encoding='utf-8').startswith, path.read_text; returns sorted((path for path in (REPOSITORY_ROOT / 'docs').rglob('*.md') if not path.read_text(encoding='utf-8').startswith('<…. No direct raise statement appears in this definition.

View source #L92-L101.

scripts.mkdocs_hooks.on_post_build · function 
scripts.mkdocs_hooks.on_post_build(config, **kwargs) -> None

Write Markdown mirrors, the API inventory, and the full LLM corpus.

Parameters

Name Type Required Default Description
config not annotated yes none Required positional or keyword input.
**kwargs not annotated no none Additional variadic keyword inputs accepted by this callable.

Returns

  • Type: None

Exceptions and behavior

Function on_post_build calls Path, build_inventory, build_repository_inventory, build_cli_inventory. No direct raise statement appears in this definition.

View source #L104-L225.

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
_source_revision function _source_revision() -> str Return the immutable commit represented by this documentation build. #L27-L46
_pin_source_links function _pin_source_links(text: str, revision: str) -> str Replace mutable gh-pages source links with one commit permalink. #L49-L55
on_page_markdown function on_page_markdown(markdown: str, **kwargs) -> str Pin every rendered GitHub source link to the build commit. #L58-L62
on_post_page function on_post_page(output: str, page = None, **kwargs) -> str Normalize search alternates and localized homepage presentation. #L65-L89
_markdown_documents function _markdown_documents() -> list[Path] Return tracked hand-written documentation pages in stable order. #L92-L101
on_post_build function on_post_build(config, **kwargs) -> None Write Markdown mirrors, the API inventory, and the full LLM corpus. #L104-L225