Building the Documentation

The documentation is built with Sphinx using the Read the Docs theme.

Prerequisites

Install the development dependencies (includes Sphinx and the theme):

pip install -e .[dev]

Building locally

On Linux / macOS:

make -C docs html

On Windows:

cd docs
make.bat html

The generated site is written to docs/_build/html/. Open docs/_build/html/index.html in a browser to view it.

To rebuild from scratch (useful after structural changes):

make -C docs clean html

Sphinx configuration

The configuration lives in docs/conf.py. Notable settings:

Extensions:

  • sphinx.ext.autodoc - pulls docstrings from Python source files into the

    documentation via .. autoclass:: and .. autofunction:: directives.

  • sphinx.ext.intersphinx - cross-references to the Python standard library documentation (e.g. :class:`~types.SimpleNamespace` links to the stdlib docs).

``sys.path`` insertion:

docs/conf.py adds src/ to sys.path so that autodoc can import the pyplanner package without requiring it to be installed into the Sphinx build environment.

Image mirroring

README.rst references images as docs/images/* (correct when viewed from the repository root on GitHub). When Sphinx includes README.rst from docs/index.rst it resolves paths relative to docs/, looking for docs/docs/images/*.

To satisfy both contexts, conf.py mirrors docs/images/ to docs/docs/images/ at build time using shutil.copytree(). The mirror directory is in .gitignore.

Documentation structure

docs/
  index.rst               Root (includes README.rst)
  conf.py                 Sphinx configuration
  Makefile                Unix build targets
  make.bat                Windows build targets
  designer-guide/         Template design tutorial
    intro.rst
    project-structure.rst
    template-basics.rst
    ...
  developer-guide/        Using pyplanner as a library
    intro.rst
    calendar-and-days.rst
    holidays.rst
    ...
  internals/              Contributing to pyplanner
    intro.rst
    project-layout.rst
    testing.rst
    ...

Each section has an intro.rst with a toctree that chains its sub-pages. The top-level index.rst links to each section’s intro, creating a three-level hierarchy that reads top to bottom.

Autodoc conventions

The documentation follows a “narrative first, API reference at the bottom” pattern. Each chapter in the developer guide opens with explanatory prose and code examples, then ends with an API reference section that uses autodoc directives to pull in docstrings from the source.

This means most documentation lives in the source files as docstrings (Sphinx :param:, :returns:, :raises: fields), while the RST files provide the narrative glue and examples.

When adding a new public class or function:

  1. Write a docstring in the source file.

  2. Add a .. autoclass:: or .. autofunction:: directive in the appropriate RST chapter’s API reference section.

  3. If the class or function introduces a new concept, add explanatory prose and examples above the API reference.

Deploying to GitHub Pages

The build-sphinx-docs.yml workflow runs on every push to main. It builds the HTML documentation and deploys it to GitHub Pages automatically. No manual deployment is needed.