# Documentation

## Building Locally

```bash
cd doc
uv run make html
```

The output is generated in `doc/_build/html/`.

For live-reload during editing:

```bash
cd doc
uv run sphinx-autobuild . _build/html
```

## Multi-version Build

The CI workflow (`.github/workflows/documentation.yml`) uses
[sphinx-multiversion](https://github.com/sphinx-contrib/multiversion)
to build documentation for all versions listed in `_static/versions.json`.

Each version's `conf.py` is loaded independently, so CI must install
all dependencies required by older versions' `conf.py` files.

Version-specific dependencies:

| Version | Dependency | Reason | Remove when |
|---------|------------|--------|-------------|
| v0.6.1 | `jupytext` | `conf.py` imports jupytext | v0.6.1 dropped from `versions.json` |

When removing a version from `versions.json`, also remove its dependencies
from `.github/workflows/documentation.yml`.

## Release Workflow

1. Merge the PR generated by [Release Please](https://github.com/googleapis/release-please)
2. Build and publish the package using uv
3. Merge the PR of conda-forge/ktch-feedstock

To force a specific version number, use `Release-As` in the commit body:

```bash
git commit --allow-empty -m "chore: release x.x.x" -m "Release-As: x.x.x"
```

See [How do I change the version number?](https://github.com/googleapis/release-please?tab=readme-ov-file#how-do-i-change-the-version-number)
for details.

## License Check

[LicenseCheck](https://github.com/FHPythonUtils/LicenseCheck) verifies that
all dependency licenses are compatible with the project license (Apache-2.0).
Licenses to reject are configured in `pyproject.toml` under `[tool.licensecheck]`.

```bash
uv run licensecheck -r pyproject.toml --zero
```

`--zero` returns a non-zero exit code if an incompatible license is found,
suitable for CI use.

## License

The documentation is licensed under a
Creative Commons Attribution 4.0 International (CC BY 4.0) License.

The documentation system may also include some components licensed under
open source licenses.

### scikit-learn

The following items forked from
[scikit-learn](https://github.com/scikit-learn/scikit-learn)
are licensed under the BSD 3-Clause License.

- `sphinxext/override_pst_pagetoc.py`
- `_templates/base.rst`
