Documentation Building

scaldys-project build docs builds every documentation unit found under the docs/ directory of your project. Each immediate subdirectory of docs/ is treated as an independent unit — there is no fixed set of names and no limit on how many units a project can have.

Requirements

Install the [docs] extra:

uv add --dev "scaldys-project[docs]"

This installs Sphinx and the sphinx-rtd-theme.

Engine auto-detection

scaldys-project inspects each docs/<name>/ subdirectory to determine which documentation engine to use:

Marker file present in `docs/<name>/`	Engine used
`source/conf.py`	Sphinx — runs `sphinx-build` for HTML and single-page HTML output
`mkdocs.yml`	MkDocs — detected but not yet supported; a warning is logged and the directory is skipped
(neither)	Unknown — a warning is logged and the directory is skipped

If a directory contains both source/conf.py and mkdocs.yml, Sphinx takes priority.

Sphinx documentation units

Any subdirectory whose source/conf.py is present is built as a Sphinx project. The builder produces two output formats:

Multi-page HTML (html builder):

build/<name>/html/

Single-page HTML (singlehtml builder):

build/<name>/singlehtml/

The <name> in the output path matches the subdirectory name exactly, so docs/manual/ produces build/manual/, docs/help/ produces build/help/, and so on.

Expected subdirectory layout for a Sphinx unit:

docs/
    manual/
        source/
            conf.py         ← Sphinx configuration
            index.rst       ← documentation root
            ...             ← additional RST pages
        Makefile            ← optional, generated by sphinx-quickstart
        make.bat            ← optional, generated by sphinx-quickstart

If you have not set up Sphinx yet, run sphinx-quickstart docs/<name> to generate the scaffolding.

Sphinx configuration tips

The conf.py at docs/<name>/source/conf.py is standard Sphinx. A minimal configuration that works well with scaldys-project:

project = "myapp"
copyright = "2024-2026, My Company"
author = "My Company"

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
]

html_theme = "sphinx_rtd_theme"

scaldys-project does not override any conf.py settings.

Build output:

build/<name>/html/
build/<name>/singlehtml/

This output is useful for browsing the documentation during development but is typically not included in the Windows installer (see Distribution of built docs below).

Distribution of built docs

Not every documentation unit needs to be shipped to end users. Use [docs] public_doc_dirs in scaldys-project.toml to declare which built units the packager should copy into the distribution:

[docs]
public_doc_dirs = ["manual"]

The exact output locations depend on deployment_mode:

pyinstaller / pyruntime mode

Each listed name is copied from build/<name>/html/ into two locations:

artifacts/portable/documentation/<name>/ — bundled inside the portable package and picked up by the Inno Setup installer.
artifacts/documentation/<name>/ — a standalone documentation-only copy.

wheel_only mode

Each listed name is copied from build/<name>/html/ into one location:

artifacts/documentation/<name>/ — no installer or portable package is produced in this mode, so only the standalone copy is created.

If a name is absent from public_doc_dirs, its built output is never included in the distribution but is still produced during the docs step.

An empty (or absent) public_doc_dirs means no documentation is distributed — useful when all doc units are for internal/developer use only.

Build output summary

Given an example project with two documentation units — manual and developer_guide — the build output is:

Path	Contents
`build/manual/html/`	User guide, multi-page HTML
`build/manual/singlehtml/`	User guide, single-page HTML
`build/developer_guide/html/`	Developer / API guide, multi-page HTML
`build/developer_guide/singlehtml/`	Developer / API guide, single-page HTML

With public_doc_dirs = ["manual"] in scaldys-project.toml, the distribution contains:

In pyinstaller / pyruntime mode:

artifacts/portable/documentation/manual/   ← bundled in the portable package
artifacts/documentation/manual/            ← standalone docs-only copy

In wheel_only mode:

artifacts/documentation/manual/            ← standalone docs-only copy