Build the documentation

This guide (docs/soju/, reStructuredText) is command-oriented — there is no Python API/class reference. Building is a thin wrapper around docs/Makefile, which calls sphinx-build / sphinx-autobuild under the hood.

With Compose (poe up), Sphinx HTML is at http://localhost:14323/ (live-reload). Build output is a Compose volume at /app/docs-build (not docs/_build on the host), so host poe docs / make clean stay writable and doctrees stay separate from a host Python build. With poe up-prod, docs are at http://localhost:8080/docs/ behind nginx (baked HTML). Rebuild images after dependency changes (uv run poe build).

For live-reload while editing RST on the host (optional; uses :14323 and conflicts with nothing in Compose because docs are internal-only):

uv run poe docs          # HTML → docs/_build/html/
uv run poe docs-serve    # live-reload preview on :14323, opens a browser tab
uv run poe docs-serve --port 9000

Equivalent to running make directly from docs/:

make -C docs html
make -C docs clean
make -C docs serve              # default PORT=14323
make -C docs serve PORT=9000
# Windows: docs\make.bat html

CLI option help (e.g. --level) is generated at build time from the live Typer apps via sphinxcontrib-typer, which needs DATA_DIR to resolve; docs/conf.py defaults it to the repo’s data/ directory automatically, so no extra setup is required.

Theme

The HTML theme defaults to furo and is configurable via the SPHINX_THEME environment variable (the theme package must already be installed):

make -C docs html SPHINX_THEME=alabaster

Adding a page

  1. Create an .rst file under docs/soju/development/ or docs/soju/cli/.

  2. List it in the matching toctree in the root Soju (소주) Platform. Pages intentionally left out of every toctree (e.g. section overview pages) need an :orphan: field list at the top, or Sphinx warns that the document “isn’t included in any toctree”.

  3. Rebuild with uv run poe docs and check the output for warnings before committing.