.. _documentation_building:

***********************
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:

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - 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``:

.. code-block:: python

    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:

.. code-block:: toml

    [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:

.. list-table::
   :header-rows: 1
   :widths: 45 55

   * - 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