Documentation development

The documentation site uses MkDocs Material, mkdocstrings, and static AST inventory tools. It publishes all existing Markdown pages, an exhaustive Python reference, and machine-readable artifacts for LLMs and coding agents.

Install documentation dependencies

python -m pip install -r docs/requirements.txt

This installs only the static documentation toolchain, so Linux builders do not need MLX. Apple Silicon developers may instead use python -m pip install -e ".[docs]" when they also want an editable runtime installation.

Preview locally

python scripts/check_docs_coverage.py
mkdocs serve

Open http://127.0.0.1:8000/. Checked-in API pages are refreshed with python scripts/gen_api_reference.py.

Run the release-equivalent build

python scripts/check_docs_coverage.py
mkdocs build --strict

Strict mode turns configuration, navigation, cross-reference, and link warnings into failures. The generated site is written to site/.

Coverage contract

scripts/check_docs_coverage.py enforces:

• One generated API page for every tracked vllm_mlx/**/*.py module.
• One source-map entry for every class, function, method, nested class, and nested function.
• One searchable symbol-index entry and callable contract for every definition.
• An explicit parameter record with kind, type, requirement, default, and description for every callable input.
• A module docstring for every module.
• A docstring for every public, addressable class, function, and method.
• Conservative implementation facts for every private or nested definition, generated from its own AST body.
• An H1 heading in every hand-written Markdown page.
• Presence of the Pages workflow and agent-facing artifacts.

The check prints module, symbol, public explanation, and Markdown page totals. New code cannot silently reduce documentation coverage.

Add or change Python code

New modules are discovered from Git-tracked Python files. No navigation file needs updating. Add a module docstring and document every public object in the source:

def resolve_model(name: str, *, allow_remote: bool = True) -> ModelSpec:
    """Resolve a user-facing model name into a validated model specification.

    Args:
        name: Registry name, local path, or supported remote identifier.
        allow_remote: Whether remote model identifiers may be resolved.

    Returns:
        The validated model specification used by the loader.

    Raises:
        ValueError: If the name is empty or incompatible with policy.
    """

Private and nested definitions are included in the source map automatically. Add a docstring when their contract or invariants are not obvious.

Add a guide

Place English pages in the appropriate docs/ section. Use a descriptive H1 and relative links between documentation pages. Add translated pages under docs/es, docs/fr, or docs/zh when a translation is available.

Every guide should distinguish:

• Supported behavior from examples or recommendations.
• Defaults from optional configuration.
• Linux-compatible checks from Apple Silicon runtime checks.
• Public contracts from implementation details.

Generated API pages

scripts/gen_api_reference.py writes deterministic, checked-in pages for every Python module. The workflow runs the generator with --check so stale pages fail CI. Each module page contains:

• Module summary and complete source link.
• Full mkdocstrings rendering with signatures, parsed parameter sections, and inline source.
• Expandable contracts for every public, private, and nested definition.
• Explicit inputs, defaults, return annotations, direct exceptions, and source-grounded behavior.
• Exact #Lx-Ly links for every definition.

docs/reference/python-symbols.md adds a filterable index over every runtime symbol and signature. Source links are stored against gh-pages for readable Markdown, then rewritten during the build to the exact commit in VLLM_MLX_DOCS_SOURCE_REVISION. This keeps #Lx-Ly permalinks correct after either branch changes.

LLM and agent artifacts

docs/llms.txt is the compact, curated index defined by the emerging llms.txt convention. scripts/mkdocs_hooks.py creates these build artifacts:

• llms-full.txt: every hand-written page plus a complete record for every Python symbol.
• api-inventory.json: structured module and symbol metadata.
• Markdown mirrors of hand-written and generated API pages.

The compact index is hand-maintained because page priority and descriptions require editorial judgment. The complete corpus and inventory are generated so they cannot drift from source.

GitHub Pages deployment

.github/workflows/docs.yml builds documentation on pull requests targeting gh-pages. A successful push to gh-pages uploads the site artifact and deploys it through the protected github-pages environment. Documentation changes stay on that dedicated branch and do not need to enter main.

Repository administrators must select GitHub Actions as the Pages publishing source once in repository settings. The workflow uses least-privilege permissions: the build reads contents, and only the deploy job receives pages: write and id-token: write.

Review checklist

• Run the coverage check and strict build.
• Open the changed page in the local preview.
• Verify commands and request examples against current code.
• Follow every new relative link.
• Confirm source links use the correct module, immutable commit, and line range.
• Inspect site/llms.txt, site/llms-full.txt, and site/api-inventory.json.
• Check that no generated site/ content is staged.
• Run focused tests when documentation tools or source docstrings change.