# Building the documentation

The site uses Sphinx 9.2.0 and PyData Sphinx Theme 0.20.0, the theme version used
by the supplied pandas site reference. PipeWhy has its own branding and prose.
MyST renders the Markdown guides; sphinx-design supplies the four entry cards.
These are optional documentation dependencies, not core runtime dependencies.

## Build and preview

From the repository root:

```console
poetry sync --with docs
poetry run python tools/build_docs.py
poetry run python -m http.server 8000 --bind 127.0.0.1 --directory docs/_build/html
```

Open <http://127.0.0.1:8000/>. Stop the server with Ctrl+C. No external hosting
service is needed. Keep every optional extra you intend to use in the `sync`
invocation. The reference API pages do not execute scans or require a GPU.

The build treats every Sphinx warning as an error. It produces:

- `docs/_build/html/index.html`: the complete site with bundled theme assets.
- `dist/pipewhy-docs.zip`: a portable copy with `index.html` at the archive root.
- `docs/_build/html/pipewhy-docs.zip`: the same archive, linked from the homepage.

Extract the ZIP before opening `index.html`. Pages, styles and theme assets work
offline. A browser may restrict search on `file:` URLs; the local server above
avoids that restriction. Source and issue links require repository access.
External source and dependency links require internet access.

## Edit the site

The README introduces the project. Longer examples live under `docs/user_guide/`;
API directives live under `docs/reference/`. The homepage and section indexes
define the navigation. Versioned contracts are linked as downloadable text files
from the [architecture page](architecture.rst).

Run `poetry run python tools/quality.py` after changing Python configuration or
build tooling, then rebuild the docs. CI performs the same warning-free site
build in addition to the existing quality and installed-package checks.