# `scripts.docs_inventory`

Static source inventory shared by the documentation build tools.

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

## 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.docs_inventory
    options:
      members:
        - REPOSITORY_URL
        - SOURCE_BRANCH
        - REPOSITORY_ROOT
        - Parameter
        - Symbol
        - Module
        - CLIOption
        - _tracked_python_files
        - module_name_for_path
        - page_path_for_module
        - _first_sentence
        - _parameter_descriptions
        - _function_parameters
        - _class_parameters
        - _owned_nodes
        - _ordered_unique
        - _short_expression
        - _attribute_name
        - _implementation_facts
        - _function_signature
        - _class_signature
        - _defined_member_names
        - scan_python_file
        - build_inventory
        - build_repository_inventory
        - _literal_or_source
        - scan_cli_options
        - build_cli_inventory
        - _escape_table_cell
        - render_callable_signature
        - _symbol_details_url
        - render_contract_details
        - render_source_map
        - render_symbol_index
        - render_module_page
        - render_module_for_llms
        - render_cli_reference
      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.docs_inventory.Parameter" markdown="1">
<summary><code>scripts.docs_inventory.Parameter</code> · class</summary>

```python
scripts.docs_inventory.Parameter(name: str, kind: str, annotation: str, default: str, required: bool, description: str)
```

One explicit callable input reconstructed from the Python AST.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `str` | `yes` | `none` | Required constructor field. |
| `kind` | `str` | `yes` | `none` | Required constructor field. |
| `annotation` | `str` | `yes` | `none` | Required constructor field. |
| `default` | `str` | `yes` | `none` | Required constructor field. |
| `required` | `bool` | `yes` | `none` | Required constructor field. |
| `description` | `str` | `yes` | `none` | Required constructor field. |

**Returns**

- Constructs: `scripts.docs_inventory.Parameter`

**Exceptions and behavior**

Class `Parameter` declares 1 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L24-L37](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L24-L37).

</details>

<details class="api-contract" id="contract-scripts.docs_inventory.Parameter.to_dict" markdown="1">
<summary><code>scripts.docs_inventory.Parameter.to_dict</code> · method</summary>

```python
scripts.docs_inventory.Parameter.to_dict() -> dict[str, object]
```

Return a JSON-serializable representation of the parameter.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `dict[str, object]`
- Direct return expressions: `asdict(self)`

**Exceptions and behavior**

Method `Parameter.to_dict` calls `asdict`; returns `asdict(self)`.
No direct `raise` statement appears in this definition.

[View source #L34-L37](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L34-L37).

</details>

<details class="api-contract" id="contract-scripts.docs_inventory.Symbol" markdown="1">
<summary><code>scripts.docs_inventory.Symbol</code> · class</summary>

```python
scripts.docs_inventory.Symbol(name: str, qualname: str, full_name: str, kind: str, signature: str, parameters: tuple[Parameter, ...], return_annotation: str, docstring: str, summary: str, implementation: str, documented: bool, public: bool, addressable: bool, line: int, end_line: int, source_url: str, decorators: tuple[str, ...], calls: tuple[str, ...], state_reads: tuple[str, ...], state_writes: tuple[str, ...], raises: tuple[str, ...], return_expressions: tuple[str, ...], awaits: bool, yields: bool)
```

A class, function, method, or nested definition found in source code.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `str` | `yes` | `none` | Required constructor field. |
| `qualname` | `str` | `yes` | `none` | Required constructor field. |
| `full_name` | `str` | `yes` | `none` | Required constructor field. |
| `kind` | `str` | `yes` | `none` | Required constructor field. |
| `signature` | `str` | `yes` | `none` | Required constructor field. |
| `parameters` | `tuple[Parameter, ...]` | `yes` | `none` | Required constructor field. |
| `return_annotation` | `str` | `yes` | `none` | Required constructor field. |
| `docstring` | `str` | `yes` | `none` | Required constructor field. |
| `summary` | `str` | `yes` | `none` | Required constructor field. |
| `implementation` | `str` | `yes` | `none` | Required constructor field. |
| `documented` | `bool` | `yes` | `none` | Required constructor field. |
| `public` | `bool` | `yes` | `none` | Required constructor field. |
| `addressable` | `bool` | `yes` | `none` | Required constructor field. |
| `line` | `int` | `yes` | `none` | Required constructor field. |
| `end_line` | `int` | `yes` | `none` | Required constructor field. |
| `source_url` | `str` | `yes` | `none` | Required constructor field. |
| `decorators` | `tuple[str, ...]` | `yes` | `none` | Required constructor field. |
| `calls` | `tuple[str, ...]` | `yes` | `none` | Required constructor field. |
| `state_reads` | `tuple[str, ...]` | `yes` | `none` | Required constructor field. |
| `state_writes` | `tuple[str, ...]` | `yes` | `none` | Required constructor field. |
| `raises` | `tuple[str, ...]` | `yes` | `none` | Required constructor field. |
| `return_expressions` | `tuple[str, ...]` | `yes` | `none` | Required constructor field. |
| `awaits` | `bool` | `yes` | `none` | Required constructor field. |
| `yields` | `bool` | `yes` | `none` | Required constructor field. |

**Returns**

- Constructs: `scripts.docs_inventory.Symbol`

**Exceptions and behavior**

Class `Symbol` declares 1 direct member(s).
No direct `raise` statement appears in this definition.

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

</details>

<details class="api-contract" id="contract-scripts.docs_inventory.Symbol.to_dict" markdown="1">
<summary><code>scripts.docs_inventory.Symbol.to_dict</code> · method</summary>

```python
scripts.docs_inventory.Symbol.to_dict() -> dict[str, object]
```

Return a JSON-serializable representation of the symbol.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `dict[str, object]`
- Direct return expressions: `asdict(self)`

**Exceptions and behavior**

Method `Symbol.to_dict` calls `asdict`; returns `asdict(self)`.
No direct `raise` statement appears in this definition.

[View source #L69-L72](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L69-L72).

</details>

<details class="api-contract" id="contract-scripts.docs_inventory.Module" markdown="1">
<summary><code>scripts.docs_inventory.Module</code> · class</summary>

```python
scripts.docs_inventory.Module(name: str, path: str, page_path: str, docstring: str, summary: str, line_count: int, source_url: str, members: tuple[str, ...], symbols: tuple[Symbol, ...])
```

Documentation metadata for one tracked Python module.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `str` | `yes` | `none` | Required constructor field. |
| `path` | `str` | `yes` | `none` | Required constructor field. |
| `page_path` | `str` | `yes` | `none` | Required constructor field. |
| `docstring` | `str` | `yes` | `none` | Required constructor field. |
| `summary` | `str` | `yes` | `none` | Required constructor field. |
| `line_count` | `int` | `yes` | `none` | Required constructor field. |
| `source_url` | `str` | `yes` | `none` | Required constructor field. |
| `members` | `tuple[str, ...]` | `yes` | `none` | Required constructor field. |
| `symbols` | `tuple[Symbol, ...]` | `yes` | `none` | Required constructor field. |

**Returns**

- Constructs: `scripts.docs_inventory.Module`

**Exceptions and behavior**

Class `Module` declares 1 direct member(s).
No direct `raise` statement appears in this definition.

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

</details>

<details class="api-contract" id="contract-scripts.docs_inventory.Module.to_dict" markdown="1">
<summary><code>scripts.docs_inventory.Module.to_dict</code> · method</summary>

```python
scripts.docs_inventory.Module.to_dict() -> dict[str, object]
```

Return a JSON-serializable representation of the module.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `dict[str, object]`
- Direct return expressions: `payload`

**Exceptions and behavior**

Method `Module.to_dict` calls `asdict`, `symbol.to_dict`; returns `payload`.
No direct `raise` statement appears in this definition.

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

</details>

<details class="api-contract" id="contract-scripts.docs_inventory.CLIOption" markdown="1">
<summary><code>scripts.docs_inventory.CLIOption</code> · class</summary>

```python
scripts.docs_inventory.CLIOption(context: str, receiver: str, flags: tuple[str, ...], destination: str, description: str, default: str, required: bool, choices: str, action: str, path: str, line: int, end_line: int, source_url: str)
```

One argparse option declaration found in executable source.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `context` | `str` | `yes` | `none` | Required constructor field. |
| `receiver` | `str` | `yes` | `none` | Required constructor field. |
| `flags` | `tuple[str, ...]` | `yes` | `none` | Required constructor field. |
| `destination` | `str` | `yes` | `none` | Required constructor field. |
| `description` | `str` | `yes` | `none` | Required constructor field. |
| `default` | `str` | `yes` | `none` | Required constructor field. |
| `required` | `bool` | `yes` | `none` | Required constructor field. |
| `choices` | `str` | `yes` | `none` | Required constructor field. |
| `action` | `str` | `yes` | `none` | Required constructor field. |
| `path` | `str` | `yes` | `none` | Required constructor field. |
| `line` | `int` | `yes` | `none` | Required constructor field. |
| `end_line` | `int` | `yes` | `none` | Required constructor field. |
| `source_url` | `str` | `yes` | `none` | Required constructor field. |

**Returns**

- Constructs: `scripts.docs_inventory.CLIOption`

**Exceptions and behavior**

Class `CLIOption` declares 1 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L98-L118](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L98-L118).

</details>

<details class="api-contract" id="contract-scripts.docs_inventory.CLIOption.to_dict" markdown="1">
<summary><code>scripts.docs_inventory.CLIOption.to_dict</code> · method</summary>

```python
scripts.docs_inventory.CLIOption.to_dict() -> dict[str, object]
```

Return a JSON-serializable representation of the option.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `dict[str, object]`
- Direct return expressions: `asdict(self)`

**Exceptions and behavior**

Method `CLIOption.to_dict` calls `asdict`; returns `asdict(self)`.
No direct `raise` statement appears in this definition.

[View source #L115-L118](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L115-L118).

</details>

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

```python
scripts.docs_inventory._tracked_python_files(root: Path, source_roots: tuple[str, ...] = ('vllm_mlx',)) -> list[Path]
```

Return tracked modules under selected roots, with a filesystem fallback.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `root` | `Path` | `yes` | `none` | Required positional or keyword input. |
| `source_roots` | `tuple[str, ...]` | `no` | `('vllm_mlx',)` | Optional positional or keyword input; defaults to `('vllm_mlx',)`. |

**Returns**

- Type: `list[Path]`
- Direct return expressions: `sorted(tracked)`; `sorted((path for source_root in source_roots for path in (root / source_root).rglob('*.py')))`

**Exceptions and behavior**

Function `_tracked_python_files` calls `subprocess.run`, `completed.stdout.splitlines`, `path.relative_to`, `sorted`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L121-L154](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L121-L154).

</details>

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

```python
scripts.docs_inventory.module_name_for_path(path: Path, root: Path = REPOSITORY_ROOT) -> str
```

Convert a package source path into its importable dotted module name.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `path` | `Path` | `yes` | `none` | Required positional or keyword input. |
| `root` | `Path` | `no` | `REPOSITORY_ROOT` | Optional positional or keyword input; defaults to `REPOSITORY_ROOT`. |

**Returns**

- Type: `str`
- Direct return expressions: `'.'.join(parts)`

**Exceptions and behavior**

Function `module_name_for_path` calls `path.relative_to(root).with_suffix`, `path.relative_to`, `list`, `parts.pop`; returns `'.'.join(parts)`.
No direct `raise` statement appears in this definition.

[View source #L157-L164](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L157-L164).

</details>

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

```python
scripts.docs_inventory.page_path_for_module(path: Path, root: Path = REPOSITORY_ROOT) -> Path
```

Return the generated documentation path for a package source file.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `path` | `Path` | `yes` | `none` | Required positional or keyword input. |
| `root` | `Path` | `no` | `REPOSITORY_ROOT` | Optional positional or keyword input; defaults to `REPOSITORY_ROOT`. |

**Returns**

- Type: `Path`
- Direct return expressions: `Path('reference') / section / relative`

**Exceptions and behavior**

Function `page_path_for_module` calls `path.relative_to(root).with_suffix`, `path.relative_to`, `relative.with_name`, `Path`; returns `Path('reference') / section / relative`.
No direct `raise` statement appears in this definition.

[View source #L167-L174](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L167-L174).

</details>

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

```python
scripts.docs_inventory._first_sentence(docstring: str) -> str
```

Return a compact first sentence or line from a docstring.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `docstring` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `''`; `text[:match.start()] if match else text`

**Exceptions and behavior**

Function `_first_sentence` calls `' '.join`, `docstring.strip().split`, `docstring.strip`, `re.search`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L177-L184](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L177-L184).

</details>

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

```python
scripts.docs_inventory._parameter_descriptions(docstring: str) -> dict[str, str]
```

Extract Google, NumPy, and Sphinx parameter descriptions.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `docstring` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

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

**Exceptions and behavior**

Function `_parameter_descriptions` calls `docstring.splitlines`, `re.match`, `sphinx_match.group(1).lstrip`, `sphinx_match.group`; returns `descriptions`.
No direct `raise` statement appears in this definition.

[View source #L187-L266](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L187-L266).

</details>

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

```python
scripts.docs_inventory._function_parameters(node: ast.FunctionDef | ast.AsyncFunctionDef, docstring: str) -> tuple[Parameter, ...]
```

Return the callable inputs, annotations, defaults, and descriptions.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `node` | `ast.FunctionDef \| ast.AsyncFunctionDef` | `yes` | `none` | Required positional or keyword input. |
| `docstring` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `tuple[Parameter, ...]`
- Direct return expressions: `tuple(parameters)`

**Exceptions and behavior**

Function `_function_parameters` calls `_parameter_descriptions`, `len`, `list`, `enumerate`; returns `tuple(parameters)`.
No direct `raise` statement appears in this definition.

[View source #L269-L353](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L269-L353).

</details>

<details class="api-contract" id="contract-scripts.docs_inventory._function_parameters.append_parameter" markdown="1">
<summary><code>scripts.docs_inventory._function_parameters.append_parameter</code> · nested function</summary>

```python
scripts.docs_inventory._function_parameters.append_parameter(argument: ast.arg, *, kind: str, default_node: ast.AST | None, required: bool, prefix: str = '') -> None
```

Nested Function `_function_parameters.append_parameter` calls `_short_expression`, `descriptions.get`, `parameters.append`, `Parameter`; returns `None`.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `argument` | `ast.arg` | `yes` | `none` | Required positional or keyword input. |
| `kind` | `str` | `yes` | `none` | Required keyword-only input. |
| `default_node` | `ast.AST \| None` | `yes` | `none` | Required keyword-only input. |
| `required` | `bool` | `yes` | `none` | Required keyword-only input. |
| `prefix` | `str` | `no` | `''` | Optional keyword-only input; defaults to `''`. |

**Returns**

- Type: `None`
- Direct return expressions: `None`

**Exceptions and behavior**

Nested Function `_function_parameters.append_parameter` calls `_short_expression`, `descriptions.get`, `parameters.append`, `Parameter`; returns `None`.
No direct `raise` statement appears in this definition.

[View source #L282-L314](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L282-L314).

</details>

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

```python
scripts.docs_inventory._class_parameters(node: ast.ClassDef, docstring: str) -> tuple[Parameter, ...]
```

Return constructor inputs from ``__init__`` or declarative fields.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `node` | `ast.ClassDef` | `yes` | `none` | Required positional or keyword input. |
| `docstring` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `tuple[Parameter, ...]`
- Direct return expressions: `_function_parameters(initializer, '\n'.join((part for part in (docstring, initializer_docstring) if part)))`; `()`; `tuple(parameters)`

**Exceptions and behavior**

Function `_class_parameters` calls `next`, `isinstance`, `ast.get_docstring`, `_function_parameters`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L356-L408](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L356-L408).

</details>

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

```python
scripts.docs_inventory._owned_nodes(node: ast.AST) -> Iterable[ast.AST]
```

Walk implementation nodes without attributing nested bodies to parents.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `node` | `ast.AST` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `Iterable[ast.AST]`
- Yields values incrementally.

**Exceptions and behavior**

Function `_owned_nodes` calls `getattr`, `list`, `reversed`, `stack.pop`; yields values incrementally.
No direct `raise` statement appears in this definition.

[View source #L411-L423](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L411-L423).

</details>

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

```python
scripts.docs_inventory._ordered_unique(values: Iterable[str]) -> tuple[str, ...]
```

Return non-empty strings once while preserving their source order.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `values` | `Iterable[str]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `tuple[str, ...]`
- Direct return expressions: `tuple(dict.fromkeys((value for value in values if value)))`

**Exceptions and behavior**

Function `_ordered_unique` calls `tuple`, `dict.fromkeys`; returns `tuple(dict.fromkeys((value for value in values if value)))`.
No direct `raise` statement appears in this definition.

[View source #L426-L429](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L426-L429).

</details>

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

```python
scripts.docs_inventory._short_expression(node: ast.AST | None, *, limit: int = 120) -> str
```

Render an AST expression without allowing one fact to dominate output.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `node` | `ast.AST \| None` | `yes` | `none` | Required positional or keyword input. |
| `limit` | `int` | `no` | `120` | Optional keyword-only input; defaults to `120`. |

**Returns**

- Type: `str`
- Direct return expressions: `'None'`; `value if len(value) <= limit else value[:limit - 1] + '…'`

**Exceptions and behavior**

Function `_short_expression` calls `' '.join`, `ast.unparse(node).split`, `ast.unparse`, `len`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L432-L438](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L432-L438).

</details>

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

```python
scripts.docs_inventory._attribute_name(node: ast.Attribute) -> str
```

Return tracked ``self`` or ``cls`` attribute access, if applicable.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `node` | `ast.Attribute` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `'.'.join(reversed(parts))`; `''`

**Exceptions and behavior**

Function `_attribute_name` calls `isinstance`, `parts.append`, `'.'.join`, `reversed`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L441-L452](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L441-L452).

</details>

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

```python
scripts.docs_inventory._implementation_facts(node: ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef, *, kind: str, qualname: str) -> dict[str, object]
```

Extract conservative behavioral facts from one definition's own body.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `node` | `ast.ClassDef \| ast.FunctionDef \| ast.AsyncFunctionDef` | `yes` | `none` | Required positional or keyword input. |
| `kind` | `str` | `yes` | `none` | Required keyword-only input. |
| `qualname` | `str` | `yes` | `none` | Required keyword-only input. |

**Returns**

- Type: `dict[str, object]`
- Direct return expressions: `{'implementation': implementation, 'decorators': decorators, 'calls': (), 'state_reads': (), 'state_writes': (), 'raise…`; `{'implementation': implementation, 'decorators': decorators, 'calls': calls, 'state_reads': state_reads, 'state_writes'…`

**Exceptions and behavior**

Function `_implementation_facts` calls `_ordered_unique`, `ast.unparse`, `isinstance`, `clauses.append`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L455-L548](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L455-L548).

</details>

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

```python
scripts.docs_inventory._function_signature(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str
```

Render a stable function signature without importing its module.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `node` | `ast.FunctionDef \| ast.AsyncFunctionDef` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `f'{prefix} {node.name}({ast.unparse(node.args)}){returns}'`

**Exceptions and behavior**

Function `_function_signature` calls `isinstance`, `ast.unparse`; returns `f'{prefix} {node.name}({ast.unparse(node.args)}){returns}'`.
No direct `raise` statement appears in this definition.

[View source #L551-L556](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L551-L556).

</details>

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

```python
scripts.docs_inventory._class_signature(node: ast.ClassDef) -> str
```

Render a class declaration and its bases from the AST.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `node` | `ast.ClassDef` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `f'class {node.name}{suffix}'`

**Exceptions and behavior**

Function `_class_signature` calls `ast.unparse`, `arguments.extend`, `', '.join`; returns `f'class {node.name}{suffix}'`.
No direct `raise` statement appears in this definition.

[View source #L559-L565](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L559-L565).

</details>

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

```python
scripts.docs_inventory._defined_member_names(tree: ast.Module) -> tuple[str, ...]
```

Return names defined directly by a module in source order.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tree` | `ast.Module` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `tuple[str, ...]`
- Direct return expressions: `tuple(dict.fromkeys(names))`

**Exceptions and behavior**

Function `_defined_member_names` calls `isinstance`, `names.append`, `tuple`, `dict.fromkeys`; returns `tuple(dict.fromkeys(names))`.
No direct `raise` statement appears in this definition.

[View source #L568-L584](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L568-L584).

</details>

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

```python
scripts.docs_inventory.scan_python_file(path: Path, root: Path = REPOSITORY_ROOT) -> Module
```

Parse one Python file into module and symbol documentation metadata.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `path` | `Path` | `yes` | `none` | Required positional or keyword input. |
| `root` | `Path` | `no` | `REPOSITORY_ROOT` | Optional positional or keyword input; defaults to `REPOSITORY_ROOT`. |

**Returns**

- Type: `Module`
- Direct return expressions: `Module(name=module_name, path=relative_path, page_path=page_path_for_module(path, root).as_posix(), docstring=module_do…`

**Exceptions and behavior**

Function `scan_python_file` calls `path.read_text`, `ast.parse`, `str`, `ast.walk`; returns `Module(name=module_name, path=relative_path, page_path=page_path_for_module(path, root).as_posix(), docstring=module_do…`.
No direct `raise` statement appears in this definition.

[View source #L587-L712](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L587-L712).

</details>

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

```python
scripts.docs_inventory.build_inventory(root: Path = REPOSITORY_ROOT, source_roots: tuple[str, ...] = ('vllm_mlx',)) -> list[Module]
```

Build static source inventory for the selected repository roots.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `root` | `Path` | `no` | `REPOSITORY_ROOT` | Optional positional or keyword input; defaults to `REPOSITORY_ROOT`. |
| `source_roots` | `tuple[str, ...]` | `no` | `('vllm_mlx',)` | Optional positional or keyword input; defaults to `('vllm_mlx',)`. |

**Returns**

- Type: `list[Module]`
- Direct return expressions: `[scan_python_file(path, root) for path in _tracked_python_files(root, source_roots)]`

**Exceptions and behavior**

Function `build_inventory` calls `scan_python_file`, `_tracked_python_files`; returns `[scan_python_file(path, root) for path in _tracked_python_files(root, source_roots)]`.
No direct `raise` statement appears in this definition.

[View source #L715-L724](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L715-L724).

</details>

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

```python
scripts.docs_inventory.build_repository_inventory(root: Path = REPOSITORY_ROOT) -> list[Module]
```

Inventory runtime, documentation tools, and executable examples.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `root` | `Path` | `no` | `REPOSITORY_ROOT` | Optional positional or keyword input; defaults to `REPOSITORY_ROOT`. |

**Returns**

- Type: `list[Module]`
- Direct return expressions: `build_inventory(root, ('vllm_mlx', 'scripts', 'examples'))`

**Exceptions and behavior**

Function `build_repository_inventory` calls `build_inventory`; returns `build_inventory(root, ('vllm_mlx', 'scripts', 'examples'))`.
No direct `raise` statement appears in this definition.

[View source #L727-L730](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L727-L730).

</details>

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

```python
scripts.docs_inventory._literal_or_source(node: ast.AST | None, default: str = '') -> str
```

Render a simple literal cleanly and preserve expressions as source.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `node` | `ast.AST \| None` | `yes` | `none` | Required positional or keyword input. |
| `default` | `str` | `no` | `''` | Optional positional or keyword input; defaults to `''`. |

**Returns**

- Type: `str`
- Direct return expressions: `default`; `' '.join(ast.unparse(node).split())`; `' '.join(value.split())`; `repr(value)`

**Exceptions and behavior**

Function `_literal_or_source` calls `ast.literal_eval`, `' '.join`, `ast.unparse(node).split`, `ast.unparse`; has 4 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L733-L744](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L733-L744).

</details>

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

```python
scripts.docs_inventory.scan_cli_options(paths: Iterable[Path], root: Path = REPOSITORY_ROOT) -> list[CLIOption]
```

Extract every argparse ``add_argument`` call from selected source files.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `paths` | `Iterable[Path]` | `yes` | `none` | Required positional or keyword input. |
| `root` | `Path` | `no` | `REPOSITORY_ROOT` | Optional positional or keyword input; defaults to `REPOSITORY_ROOT`. |

**Returns**

- Type: `list[CLIOption]`
- Direct return expressions: `sorted(options, key=lambda option: (option.path, option.line))`

**Exceptions and behavior**

Function `scan_cli_options` calls `sorted`, `path.read_text`, `ast.parse`, `str`; returns `sorted(options, key=lambda option: (option.path, option.line))`.
No direct `raise` statement appears in this definition.

[View source #L747-L817](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L747-L817).

</details>

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

```python
scripts.docs_inventory.build_cli_inventory(root: Path = REPOSITORY_ROOT) -> list[CLIOption]
```

Build the complete argparse option inventory for executable source.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `root` | `Path` | `no` | `REPOSITORY_ROOT` | Optional positional or keyword input; defaults to `REPOSITORY_ROOT`. |

**Returns**

- Type: `list[CLIOption]`
- Direct return expressions: `scan_cli_options(paths, root)`

**Exceptions and behavior**

Function `build_cli_inventory` calls `_tracked_python_files`, `scan_cli_options`; returns `scan_cli_options(paths, root)`.
No direct `raise` statement appears in this definition.

[View source #L820-L824](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L820-L824).

</details>

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

```python
scripts.docs_inventory._escape_table_cell(value: str) -> str
```

Escape text for a compact Markdown table cell.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `' '.join(value.replace('|', '\\|').split())`

**Exceptions and behavior**

Function `_escape_table_cell` calls `' '.join`, `value.replace('|', '\\|').split`, `value.replace`; returns `' '.join(value.replace('|', '\\|').split())`.
No direct `raise` statement appears in this definition.

[View source #L827-L830](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L827-L830).

</details>

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

```python
scripts.docs_inventory.render_callable_signature(symbol: Symbol, *, qualified: bool = False) -> str
```

Render a reader-facing signature without implicit ``self`` or ``cls``.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `symbol` | `Symbol` | `yes` | `none` | Required positional or keyword input. |
| `qualified` | `bool` | `no` | `False` | Optional keyword-only input; defaults to `False`. |

**Returns**

- Type: `str`
- Direct return expressions: `signature`

**Exceptions and behavior**

Function `render_callable_signature` calls `sum`, `any`, `pieces.append`, `symbol.signature.startswith`; returns `signature`.
No direct `raise` statement appears in this definition.

[View source #L833-L866](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L833-L866).

</details>

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

```python
scripts.docs_inventory._symbol_details_url(module: Module, symbol: Symbol) -> str
```

Return the generated details URL or source fallback for one symbol.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `module` | `Module` | `yes` | `none` | Required positional or keyword input. |
| `symbol` | `Symbol` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `f'../{page_url}#contract-{symbol.full_name}'`

**Exceptions and behavior**

Function `_symbol_details_url` calls `Path(module.page_path).relative_to`, `Path`, `relative.parent.as_posix`, `relative.with_suffix('').as_posix`; returns `f'../{page_url}#contract-{symbol.full_name}'`.
No direct `raise` statement appears in this definition.

[View source #L869-L877](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L869-L877).

</details>

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

```python
scripts.docs_inventory.render_contract_details(module: Module) -> str
```

Render explicit inputs and behavior for every definition in a module.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `module` | `Module` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `'This module does not declare classes or functions.\n'`; `'\n'.join(lines)`

**Exceptions and behavior**

Function `render_contract_details` calls `lines.extend`, `render_callable_signature`, `lines.append`, `_escape_table_cell`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L880-L959](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L880-L959).

</details>

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

```python
scripts.docs_inventory.render_source_map(module: Module) -> str
```

Render a line-precise source table for every definition in a module.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `module` | `Module` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `'This module does not declare classes or functions.\n'`; `'\n'.join(lines) + '\n'`

**Exceptions and behavior**

Function `render_source_map` calls `lines.append`, `_escape_table_cell`, `render_callable_signature`, `'\n'.join`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L962-L981](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L962-L981).

</details>

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

```python
scripts.docs_inventory.render_symbol_index(modules: list[Module]) -> str
```

Render a filterable index of every runtime class and callable.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `modules` | `list[Module]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `'\n'.join(lines)`

**Exceptions and behavior**

Function `render_symbol_index` calls `sorted`, `len`, `render_callable_signature`, `' '.join((symbol.full_name, symbol.kind, signature, symbol.summary)).casefold`; returns `'\n'.join(lines)`.
No direct `raise` statement appears in this definition.

[View source #L984-L1039](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L984-L1039).

</details>

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

```python
scripts.docs_inventory.render_module_page(module: Module) -> str
```

Render the generated MkDocs page for one Python module.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `module` | `Module` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `'\n'.join(lines)`

**Exceptions and behavior**

Function `render_module_page` calls `lines.extend`, `lines.append`, `render_contract_details(module).rstrip`, `render_contract_details`; returns `'\n'.join(lines)`.
No direct `raise` statement appears in this definition.

[View source #L1042-L1086](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L1042-L1086).

</details>

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

```python
scripts.docs_inventory.render_module_for_llms(module: Module) -> str
```

Render a self-contained plain-Markdown API record for language models.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `module` | `Module` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `'\n'.join(lines) + '\n'`

**Exceptions and behavior**

Function `render_module_for_llms` calls `lines.extend`, `lines.append`, `', '.join`, `'; '.join`; returns `'\n'.join(lines) + '\n'`.
No direct `raise` statement appears in this definition.

[View source #L1089-L1144](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L1089-L1144).

</details>

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

```python
scripts.docs_inventory.render_cli_reference(options: list[CLIOption]) -> str
```

Render every discovered argparse option as a line-precise reference.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `options` | `list[CLIOption]` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `'\n'.join(lines)`

**Exceptions and behavior**

Function `render_cli_reference` calls `lines.extend`, `', '.join`, `str(option.required).lower`, `str`; returns `'\n'.join(lines)`.
No direct `raise` statement appears in this definition.

[View source #L1147-L1182](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L1147-L1182).

</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 |
| --- | --- | --- | --- | --- |
| [`Parameter`](#contract-scripts.docs_inventory.Parameter) | class | `Parameter(name: str, kind: str, annotation: str, default: str, required: bool, description: str)` | One explicit callable input reconstructed from the Python AST. | [#L24-L37](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L24-L37) |
| [`Parameter.to_dict`](#contract-scripts.docs_inventory.Parameter.to_dict) | method | `Parameter.to_dict() -> dict[str, object]` | Return a JSON-serializable representation of the parameter. | [#L34-L37](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L34-L37) |
| [`Symbol`](#contract-scripts.docs_inventory.Symbol) | class | `Symbol(name: str, qualname: str, full_name: str, kind: str, signature: str, parameters: tuple[Parameter, ...], return_annotation: str, docstring: str, summary: str, implementation: str, documented: bool, public: bool, addressable: bool, line: int, end_line: int, source_url: str, decorators: tuple[str, ...], calls: tuple[str, ...], state_reads: tuple[str, ...], state_writes: tuple[str, ...], raises: tuple[str, ...], return_expressions: tuple[str, ...], awaits: bool, yields: bool)` | A class, function, method, or nested definition found in source code. | [#L41-L72](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L41-L72) |
| [`Symbol.to_dict`](#contract-scripts.docs_inventory.Symbol.to_dict) | method | `Symbol.to_dict() -> dict[str, object]` | Return a JSON-serializable representation of the symbol. | [#L69-L72](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L69-L72) |
| [`Module`](#contract-scripts.docs_inventory.Module) | class | `Module(name: str, path: str, page_path: str, docstring: str, summary: str, line_count: int, source_url: str, members: tuple[str, ...], symbols: tuple[Symbol, ...])` | Documentation metadata for one tracked Python module. | [#L76-L94](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L76-L94) |
| [`Module.to_dict`](#contract-scripts.docs_inventory.Module.to_dict) | method | `Module.to_dict() -> dict[str, object]` | Return a JSON-serializable representation of the module. | [#L89-L94](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L89-L94) |
| [`CLIOption`](#contract-scripts.docs_inventory.CLIOption) | class | `CLIOption(context: str, receiver: str, flags: tuple[str, ...], destination: str, description: str, default: str, required: bool, choices: str, action: str, path: str, line: int, end_line: int, source_url: str)` | One argparse option declaration found in executable source. | [#L98-L118](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L98-L118) |
| [`CLIOption.to_dict`](#contract-scripts.docs_inventory.CLIOption.to_dict) | method | `CLIOption.to_dict() -> dict[str, object]` | Return a JSON-serializable representation of the option. | [#L115-L118](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L115-L118) |
| [`_tracked_python_files`](#contract-scripts.docs_inventory._tracked_python_files) | function | `_tracked_python_files(root: Path, source_roots: tuple[str, ...] = ('vllm_mlx',)) -> list[Path]` | Return tracked modules under selected roots, with a filesystem fallback. | [#L121-L154](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L121-L154) |
| [`module_name_for_path`](#contract-scripts.docs_inventory.module_name_for_path) | function | `module_name_for_path(path: Path, root: Path = REPOSITORY_ROOT) -> str` | Convert a package source path into its importable dotted module name. | [#L157-L164](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L157-L164) |
| [`page_path_for_module`](#contract-scripts.docs_inventory.page_path_for_module) | function | `page_path_for_module(path: Path, root: Path = REPOSITORY_ROOT) -> Path` | Return the generated documentation path for a package source file. | [#L167-L174](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L167-L174) |
| [`_first_sentence`](#contract-scripts.docs_inventory._first_sentence) | function | `_first_sentence(docstring: str) -> str` | Return a compact first sentence or line from a docstring. | [#L177-L184](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L177-L184) |
| [`_parameter_descriptions`](#contract-scripts.docs_inventory._parameter_descriptions) | function | `_parameter_descriptions(docstring: str) -> dict[str, str]` | Extract Google, NumPy, and Sphinx parameter descriptions. | [#L187-L266](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L187-L266) |
| [`_function_parameters`](#contract-scripts.docs_inventory._function_parameters) | function | `_function_parameters(node: ast.FunctionDef \| ast.AsyncFunctionDef, docstring: str) -> tuple[Parameter, ...]` | Return the callable inputs, annotations, defaults, and descriptions. | [#L269-L353](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L269-L353) |
| [`_function_parameters.append_parameter`](#contract-scripts.docs_inventory._function_parameters.append_parameter) | nested function | `_function_parameters.append_parameter(argument: ast.arg, *, kind: str, default_node: ast.AST \| None, required: bool, prefix: str = '') -> None` | Nested Function `_function_parameters.append_parameter` calls `_short_expression`, `descriptions.get`, `parameters.append`, `Parameter`; returns `None`. | [#L282-L314](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L282-L314) |
| [`_class_parameters`](#contract-scripts.docs_inventory._class_parameters) | function | `_class_parameters(node: ast.ClassDef, docstring: str) -> tuple[Parameter, ...]` | Return constructor inputs from ``__init__`` or declarative fields. | [#L356-L408](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L356-L408) |
| [`_owned_nodes`](#contract-scripts.docs_inventory._owned_nodes) | function | `_owned_nodes(node: ast.AST) -> Iterable[ast.AST]` | Walk implementation nodes without attributing nested bodies to parents. | [#L411-L423](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L411-L423) |
| [`_ordered_unique`](#contract-scripts.docs_inventory._ordered_unique) | function | `_ordered_unique(values: Iterable[str]) -> tuple[str, ...]` | Return non-empty strings once while preserving their source order. | [#L426-L429](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L426-L429) |
| [`_short_expression`](#contract-scripts.docs_inventory._short_expression) | function | `_short_expression(node: ast.AST \| None, *, limit: int = 120) -> str` | Render an AST expression without allowing one fact to dominate output. | [#L432-L438](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L432-L438) |
| [`_attribute_name`](#contract-scripts.docs_inventory._attribute_name) | function | `_attribute_name(node: ast.Attribute) -> str` | Return tracked ``self`` or ``cls`` attribute access, if applicable. | [#L441-L452](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L441-L452) |
| [`_implementation_facts`](#contract-scripts.docs_inventory._implementation_facts) | function | `_implementation_facts(node: ast.ClassDef \| ast.FunctionDef \| ast.AsyncFunctionDef, *, kind: str, qualname: str) -> dict[str, object]` | Extract conservative behavioral facts from one definition's own body. | [#L455-L548](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L455-L548) |
| [`_function_signature`](#contract-scripts.docs_inventory._function_signature) | function | `_function_signature(node: ast.FunctionDef \| ast.AsyncFunctionDef) -> str` | Render a stable function signature without importing its module. | [#L551-L556](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L551-L556) |
| [`_class_signature`](#contract-scripts.docs_inventory._class_signature) | function | `_class_signature(node: ast.ClassDef) -> str` | Render a class declaration and its bases from the AST. | [#L559-L565](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L559-L565) |
| [`_defined_member_names`](#contract-scripts.docs_inventory._defined_member_names) | function | `_defined_member_names(tree: ast.Module) -> tuple[str, ...]` | Return names defined directly by a module in source order. | [#L568-L584](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L568-L584) |
| [`scan_python_file`](#contract-scripts.docs_inventory.scan_python_file) | function | `scan_python_file(path: Path, root: Path = REPOSITORY_ROOT) -> Module` | Parse one Python file into module and symbol documentation metadata. | [#L587-L712](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L587-L712) |
| [`build_inventory`](#contract-scripts.docs_inventory.build_inventory) | function | `build_inventory(root: Path = REPOSITORY_ROOT, source_roots: tuple[str, ...] = ('vllm_mlx',)) -> list[Module]` | Build static source inventory for the selected repository roots. | [#L715-L724](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L715-L724) |
| [`build_repository_inventory`](#contract-scripts.docs_inventory.build_repository_inventory) | function | `build_repository_inventory(root: Path = REPOSITORY_ROOT) -> list[Module]` | Inventory runtime, documentation tools, and executable examples. | [#L727-L730](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L727-L730) |
| [`_literal_or_source`](#contract-scripts.docs_inventory._literal_or_source) | function | `_literal_or_source(node: ast.AST \| None, default: str = '') -> str` | Render a simple literal cleanly and preserve expressions as source. | [#L733-L744](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L733-L744) |
| [`scan_cli_options`](#contract-scripts.docs_inventory.scan_cli_options) | function | `scan_cli_options(paths: Iterable[Path], root: Path = REPOSITORY_ROOT) -> list[CLIOption]` | Extract every argparse ``add_argument`` call from selected source files. | [#L747-L817](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L747-L817) |
| [`build_cli_inventory`](#contract-scripts.docs_inventory.build_cli_inventory) | function | `build_cli_inventory(root: Path = REPOSITORY_ROOT) -> list[CLIOption]` | Build the complete argparse option inventory for executable source. | [#L820-L824](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L820-L824) |
| [`_escape_table_cell`](#contract-scripts.docs_inventory._escape_table_cell) | function | `_escape_table_cell(value: str) -> str` | Escape text for a compact Markdown table cell. | [#L827-L830](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L827-L830) |
| [`render_callable_signature`](#contract-scripts.docs_inventory.render_callable_signature) | function | `render_callable_signature(symbol: Symbol, *, qualified: bool = False) -> str` | Render a reader-facing signature without implicit ``self`` or ``cls``. | [#L833-L866](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L833-L866) |
| [`_symbol_details_url`](#contract-scripts.docs_inventory._symbol_details_url) | function | `_symbol_details_url(module: Module, symbol: Symbol) -> str` | Return the generated details URL or source fallback for one symbol. | [#L869-L877](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L869-L877) |
| [`render_contract_details`](#contract-scripts.docs_inventory.render_contract_details) | function | `render_contract_details(module: Module) -> str` | Render explicit inputs and behavior for every definition in a module. | [#L880-L959](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L880-L959) |
| [`render_source_map`](#contract-scripts.docs_inventory.render_source_map) | function | `render_source_map(module: Module) -> str` | Render a line-precise source table for every definition in a module. | [#L962-L981](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L962-L981) |
| [`render_symbol_index`](#contract-scripts.docs_inventory.render_symbol_index) | function | `render_symbol_index(modules: list[Module]) -> str` | Render a filterable index of every runtime class and callable. | [#L984-L1039](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L984-L1039) |
| [`render_module_page`](#contract-scripts.docs_inventory.render_module_page) | function | `render_module_page(module: Module) -> str` | Render the generated MkDocs page for one Python module. | [#L1042-L1086](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L1042-L1086) |
| [`render_module_for_llms`](#contract-scripts.docs_inventory.render_module_for_llms) | function | `render_module_for_llms(module: Module) -> str` | Render a self-contained plain-Markdown API record for language models. | [#L1089-L1144](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L1089-L1144) |
| [`render_cli_reference`](#contract-scripts.docs_inventory.render_cli_reference) | function | `render_cli_reference(options: list[CLIOption]) -> str` | Render every discovered argparse option as a line-precise reference. | [#L1147-L1182](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/scripts/docs_inventory.py#L1147-L1182) |