1Cat-vLLM/tools/generate_env_reference.py

# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
"""Generate the reference from metadata; never read the process environment."""

import argparse
from pathlib import Path

import regex as re

from tools.pre_commit.check_env_metadata import ENVS_FILE, read_metadata

OUTPUT = Path("docs/configuration/env_var_reference.md")


def render(metadata: dict[str, dict], *, include_internal: bool = False) -> str:
    def cell(value):
        parts = re.split(r"(`[^`]*`)", str(value))
        for i, part in enumerate(parts):
            if part.startswith("`"):
                continue
            part = part.replace("_", r"\_").replace("*", r"\*")
            parts[i] = re.sub(r"(?<!<)(https?://[^\s<>]+)", r"<\1>", part)
        return "".join(parts).replace("|", r"\|").replace("\n", " ")

    lines = [
        "# Environment variable reference",
        "",
        "<!-- Generated by python -m tools.generate_env_reference; do not edit. -->",
        "",
        (
            "Defaults describe an unset environment. "
            "The declaration is the public getter contract. Effective defaults include "
            "per-engine policy and the defaults of legacy direct consumers. "
            "Automatic conditions name the policy or consumer that makes the decision. "
            "An enabled option still needs its kernel's dtype, layout and "
            "native-operator checks. Runtime routing depends on those checks."
        ),
        "",
        (
            "Categories distinguish configuration, tuning, experimental, debug and "
            "deprecated controls. Prefer engine configuration and "
            "`VLLM_DISABLED_KERNELS` for migrated acceleration paths."
        ),
        "",
        (
            "This is the user reference. Internal tuning, diagnostics and "
            "compatibility aliases remain in the metadata inventory; they are not "
            "daily configuration options. Developers can render that inventory with "
            "`--include-internal --output /tmp/environment-internals.md`. "
            "See [SM70 environment surface](../design/sm70_environment_surface.md) "
            "for compatibility and removal plans."
        ),
        "",
        (
            "| Variable | Category | Description | Declared default "
            "| Effective default "
            "| Automatic conditions / legacy consumer defaults | Acceleration paths |"
        ),
        "| --- | --- | --- | --- | --- | --- | --- |",
    ]
    for name, row in sorted(metadata.items()):
        if not include_internal and not row["user_visible"]:
            continue
        fields = [
            f"`{name}`",
            row["category"],
            row["description"],
            row["declared_default"],
            row["effective_default"],
            "<br>".join(row["automatic_conditions"]) or "None",
            ", ".join(row["acceleration_paths"]) or "No SM70 path association",
        ]
        lines.append("| " + " | ".join(map(cell, fields)) + " |")
    deprecated = {
        name: row
        for name, row in metadata.items()
        if row.get("deprecated") and (include_internal or row["user_visible"])
    }
    if deprecated:
        lines.extend(
            [
                "",
                "## Retained deprecated inputs",
                "",
                "Explicit legacy inputs warn once per process and name. Deprecating an "
                "alias does not deprecate its implementation. Experiments retain their "
                "explicit entry; evidence applies only to the documented workload.",
                "",
                "| Variable | Kind | Reason | Evidence | Replacement |",
                "| --- | --- | --- | --- | --- |",
            ]
        )
        for name, row in sorted(deprecated.items()):
            fields = [
                f"`{name}`",
                row["deprecation_kind"],
                row["deprecation_reason"],
                ", ".join(row["deprecation_evidence"]),
                row["replacement"] or "None",
            ]
            lines.append("| " + " | ".join(map(cell, fields)) + " |")
    return "\n".join(lines) + "\n"


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--check", action="store_true")
    parser.add_argument(
        "--include-internal",
        action="store_true",
        help="Include compatibility, tuning and diagnostic implementation controls",
    )
    parser.add_argument("--output", type=Path, default=OUTPUT)
    args = parser.parse_args()
    metadata, errors = read_metadata(ENVS_FILE.read_text())
    if errors:
        raise SystemExit("\n".join(errors))
    expected = render(metadata, include_internal=args.include_internal)
    if args.check:
        if not args.output.exists() or args.output.read_text() != expected:
            print(f"{args.output} is stale; run python -m tools.generate_env_reference")
            return 1
    else:
        args.output.write_text(expected)
    print(f"{len(metadata)} environment registrations documented")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())