caffy 2026.7.24.post1

An independent, accessible Sphinx theme for structured library documentation

Caffy

Caffy is an independent Sphinx theme for library and API documentation. It provides responsive navigation, light and dark modes, keyboard access, and build-time semantic styling for Python API objects.

The distribution and Sphinx theme are named caffy; the Python import package is sphinx_caffy.

Requires Python >=3.12 and Sphinx >=9.1,<10. Current release: 2026.7.24.post1.

Install

uv add caffy

With pip, use python -m pip install caffy.

Select the theme in conf.py. Sphinx discovers the installed theme without an extension entry:

html_theme = "caffy"
html_theme_options = {
    "accent": "amber",             # amber, indigo, rose, or teal
    "color_mode": "auto",          # auto, light, or dark
    "navigation_depth": "4",
    "show_page_toc": "true",
}

Build with warnings treated as errors:

sphinx-build -E -j auto -n -W --keep-going -b html docs docs/_build/html

API documentation helpers

Use the metadata-only directive on package and module pages whose heading is an API name:

.. caffy-page-kind:: package
   :title-is-api-name:

Omit :title-is-api-name: when the heading is prose such as “API reference”.

Create a compatibility route without registering the Python object twice:

.. caffy-api-alias:: package.LegacyReader
   :canonical: package.storage.Reader
   :kind: class

   This route remains available for compatibility.

Projects that use caffy-api-alias with non-HTML builders must load the extension explicitly so the directive is registered independently of HTML theme discovery:

extensions = ["sphinx_caffy"]
html_theme = "caffy"

Group arbitrary code samples behind progressively enhanced tabs:

.. caffy-tabs::
   :label: Operating system

   .. caffy-tab:: Windows
      :selected:

      .. code-block:: powershell

         py -m pip install package-name

   .. caffy-tab:: Linux

      .. code-block:: bash

         python -m pip install package-name

   .. caffy-tab:: macOS

      .. code-block:: bash

         python -m pip install package-name

Labels are author-defined. Arrow keys, Home, and End move between tabs; without JavaScript and in print output, every labeled panel remains visible. Projects that build this directive with non-HTML builders must include "sphinx_caffy" in extensions.

Use Sphinx autosummary when an API directory should show each object's one-sentence description. Enable the extension in conf.py:

extensions = ["sphinx.ext.autosummary"]

Then list importable objects under their current module:

.. currentmodule:: package.storage

.. autosummary::
   :signatures: none

   Reader
   open_store

Sphinx extracts the first valid sentence from each docstring. Caffy keeps the native summary table and adds API-kind styling from build-time metadata.

Mark an ordinary Sphinx list as a kind-aware API directory:

.. rst-class:: caffy-api-index

* :py:class:`package.storage.Reader`
* :py:func:`package.open_store`

The manual caffy-api-index form is useful for route-only or hierarchical lists that do not need docstring summaries.

Add caffy-api-hierarchy for accessible expand/collapse controls on nested API lists. Generated :doc: package trees may add caffy-kind-package or caffy-kind-module to each list item.

Develop

See the specification for the public behavior and AGENTS.md for checks and release rules.

Reuse the Sphinx environment for the normal local preview:

uv run --no-sync python scripts/build_preview.py

Use --clean after changing build configuration or whenever a completely fresh output is required. The script also selects a full rebuild automatically when build-time Python inputs change or a source page is removed.

Versioning

Caffy uses calendar versions in YYYY.M.D form. A second corrective release on the same day adds a PEP 440 post-release suffix, such as 2026.7.24.post1. Release tags add a leading v, for example v2026.7.24.

License

Caffy source code is licensed under the MIT License. Sphinx is a runtime dependency and retains its BSD 2-Clause License. The theme's search template preserves the script integration contract of Sphinx's BSD-licensed basic theme. The bundled Cormorant Garamond font remains licensed under the SIL Open Font License 1.1. Its copyright notice and complete license text are distributed in OFL-Cormorant-Garamond.txt. The bundled code font is a renamed subset of Monaspace Argon and remains licensed under the SIL Open Font License 1.1. Its copyright notice and complete license text are distributed in OFL-Caffy-Code.txt.