Skip to content

Documentation Site

Human docs live under docs/.

The documentation site is built with properdocs (a fork of mkdocs) and Material for MkDocs.

  1. Configuration: ./properdocs.yaml
  2. Content: ./docs/
  3. Dependencies: ./pyproject.toml

Development Loop

  1. make docs to start the local preview server
    • If you are doing heavy refactoring and causing many broken links, it may be helpful to run in non-strict mode: uv run properdocs serve --no-strict. CI will be strict, though.
  2. Edit the markdown files in docs/

Changing Dependencies

The root pyproject.toml uses the docs dependency group to specify the dependencies for the documentation site.

There's nothing special here; just normal uv usage. Once you modify the root pyproject.toml's dependency spec, just run uv sync --group docs && uv lock.

Relevant Make Targets

Target Role
docs Local preview (properdocs serve)
docs-build Strict build — matches docs CI

Config: properdocs.yaml. Contributing nav order is controlled by docs/contributing/.pages.

Publishing

CI builds with properdocs build --strict on every PR (.github/workflows/docs.yaml). Deploy runs on a published GitHub Release or a manual workflow_dispatch.