# `scripts.gen_api_reference`

Synchronize the exhaustive static API reference with the Python source tree.

[View the complete module source at #L1-L103](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/gen_api_reference.py#L1-L103).

## 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.gen_api_reference
    options:
      members:
        - GENERATED_HEADER
        - expected_pages
        - generated_pages_on_disk
        - check
        - write
        - main
      filters: []
      show_if_no_docstring: true

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

<details class="api-contract" id="contract-scripts.gen_api_reference.expected_pages" markdown="1">
<summary><code>scripts.gen_api_reference.expected_pages</code> · function</summary>

```python
scripts.gen_api_reference.expected_pages() -> dict[Path, str]
```

Return every generated reference path and its expected contents.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `dict[Path, str]`
- Direct return expressions: `pages`

**Exceptions and behavior**

Function `expected_pages` calls `build_inventory`, `render_module_page`, `build_repository_inventory`, `render_cli_reference`; returns `pages`.
No direct `raise` statement appears in this definition.

[View source #L23-L38](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/gen_api_reference.py#L23-L38).

</details>

<details class="api-contract" id="contract-scripts.gen_api_reference.generated_pages_on_disk" markdown="1">
<summary><code>scripts.gen_api_reference.generated_pages_on_disk</code> · function</summary>

```python
scripts.gen_api_reference.generated_pages_on_disk() -> set[Path]
```

Return generated reference pages currently present in the docs tree.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `set[Path]`
- Direct return expressions: `{path for path in docs_dir.rglob('*.md') if path.read_text(encoding='utf-8').startswith(GENERATED_HEADER)}`

**Exceptions and behavior**

Function `generated_pages_on_disk` calls `docs_dir.rglob`, `path.read_text(encoding='utf-8').startswith`, `path.read_text`; returns `{path for path in docs_dir.rglob('*.md') if path.read_text(encoding='utf-8').startswith(GENERATED_HEADER)}`.
No direct `raise` statement appears in this definition.

[View source #L41-L49](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/gen_api_reference.py#L41-L49).

</details>

<details class="api-contract" id="contract-scripts.gen_api_reference.check" markdown="1">
<summary><code>scripts.gen_api_reference.check</code> · function</summary>

```python
scripts.gen_api_reference.check() -> int
```

Report missing, stale, or unexpected generated pages.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `int`
- Direct return expressions: `1`; `0`

**Exceptions and behavior**

Function `check` calls `expected_pages`, `generated_pages_on_disk`, `expected.items`, `path.exists`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L52-L73](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/gen_api_reference.py#L52-L73).

</details>

<details class="api-contract" id="contract-scripts.gen_api_reference.write" markdown="1">
<summary><code>scripts.gen_api_reference.write</code> · function</summary>

```python
scripts.gen_api_reference.write() -> int
```

Write every reference page and remove obsolete generated pages.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `int`
- Direct return expressions: `0`

**Exceptions and behavior**

Function `write` calls `expected_pages`, `generated_pages_on_disk`, `expected.keys`, `path.unlink`; returns `0`.
No direct `raise` statement appears in this definition.

[View source #L76-L86](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/gen_api_reference.py#L76-L86).

</details>

<details class="api-contract" id="contract-scripts.gen_api_reference.main" markdown="1">
<summary><code>scripts.gen_api_reference.main</code> · function</summary>

```python
scripts.gen_api_reference.main() -> int
```

Parse the synchronization mode and update or verify generated pages.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `int`
- Direct return expressions: `check() if args.check else write()`

**Exceptions and behavior**

Function `main` calls `argparse.ArgumentParser`, `parser.add_argument`, `parser.parse_args`, `check`; returns `check() if args.check else write()`.
No direct `raise` statement appears in this definition.

[View source #L89-L99](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/gen_api_reference.py#L89-L99).

</details>

## 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 |
| --- | --- | --- | --- | --- |
| [`expected_pages`](#contract-scripts.gen_api_reference.expected_pages) | function | `expected_pages() -> dict[Path, str]` | Return every generated reference path and its expected contents. | [#L23-L38](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/gen_api_reference.py#L23-L38) |
| [`generated_pages_on_disk`](#contract-scripts.gen_api_reference.generated_pages_on_disk) | function | `generated_pages_on_disk() -> set[Path]` | Return generated reference pages currently present in the docs tree. | [#L41-L49](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/gen_api_reference.py#L41-L49) |
| [`check`](#contract-scripts.gen_api_reference.check) | function | `check() -> int` | Report missing, stale, or unexpected generated pages. | [#L52-L73](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/gen_api_reference.py#L52-L73) |
| [`write`](#contract-scripts.gen_api_reference.write) | function | `write() -> int` | Write every reference page and remove obsolete generated pages. | [#L76-L86](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/gen_api_reference.py#L76-L86) |
| [`main`](#contract-scripts.gen_api_reference.main) | function | `main() -> int` | Parse the synchronization mode and update or verify generated pages. | [#L89-L99](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/gen_api_reference.py#L89-L99) |