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:

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.

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.