# Slint Python API documentation

Astro Starlight site for the Slint Python API. The API reference is generated by
`gen_mdx.py`, which walks the `slint` package (in `api/python/slint`) with
[griffe](https://mkdocstrings.github.io/griffe/) and emits one MDX page per
symbol, grouped into a sidebar group per kind (classes, enumerations,
functions, variables). The `language` submodule (Slint language structs and
enums) mirrors the same classes/enumerations split one level down.

Standard-library types in signatures (e.g. `pathlib.Path`, `typing.Optional`)
are linked to <https://docs.python.org> by resolving CPython's Sphinx inventory
(`objects.inv`), fetched at generation time. Generation requires network access
and fails if the inventory cannot be fetched.

Content lives in `src/content/docs/`. Third-party license text is generated
into `src/content/docs/generated/thirdparty.md` (gitignored) before the build.

## Prerequisites

- [Node.js](https://nodejs.org/) (v24+) and [pnpm](https://pnpm.io/)
- [uv](https://docs.astral.sh/uv/); the generator runs on Python 3.12+ (the
  `slint` sources use PEP 695 generics)
- A Rust toolchain. The `slint-python` build script generates
  `slint/language.pyi` (read by the generator for the `language` page); run
  `cargo build -p slint-python --no-default-features` once before `pnpm gen` if
  that file is missing. A Rust toolchain is also needed for `pnpm build` /
  `pnpm thirdparty`, which generate the third-party license list via
  `cargo xtask license`.

Run `pnpm install` from the repository root first.

## Commands

From `docs/python` (or prefix with `pnpm -C docs/python` from the repository root):

```sh
pnpm install     # install dependencies (usually done once from repo root)
pnpm gen         # regenerate the API reference MDX from the slint package
pnpm dev         # start dev server (runs gen first)
pnpm build       # type-check and production build (runs gen + thirdparty first)
pnpm preview     # preview the production build
pnpm thirdparty  # regenerate src/content/docs/generated/thirdparty.md only
```

The static site is output under `dist/`.

Run the generator's unit tests (pure helpers plus a fixture-package
integration test) with `uv run pytest`. Lint and type-check it with
`uv tool run ruff check` and `uvx ty check`.
