Metadata-Version: 2.4
Name: caffy
Version: 2026.7.24
Summary: An independent, accessible Sphinx theme for structured library documentation
Author: Caffy contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Nekch0/caffy
Project-URL: Documentation, https://github.com/Nekch0/caffy#readme
Project-URL: Repository, https://github.com/Nekch0/caffy.git
Project-URL: Issues, https://github.com/Nekch0/caffy/issues
Project-URL: Releases, https://github.com/Nekch0/caffy/releases
Keywords: documentation,sphinx,sphinx-theme,python,api-reference
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Sphinx :: Theme
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Sphinx<10,>=9.1
Dynamic: license-file

# 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.

![Caffy documentation in light and dark modes](docs/_assets/caffy-preview.png)

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`.

## Install

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

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

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

```rst
.. 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:

```rst
.. 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:

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

Group arbitrary code samples behind progressively enhanced tabs:

```rst
.. 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`:

```python
extensions = ["sphinx.ext.autosummary"]
```

Then list importable objects under their current module:

```rst
.. 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
.. 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](docs/reference/specification.md) for the public behavior and
[AGENTS.md](AGENTS.md) for checks and release rules.

Reuse the Sphinx environment for the normal local preview:

```console
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](src/sphinx_caffy/theme/static/fonts/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](src/sphinx_caffy/theme/static/fonts/OFL-Caffy-Code.txt).
