caffy 2026.7.24__tar.gz

caffy-2026.7.24/AGENTS.md

@@ -0,0 +1,61 @@
+# Contributor rules
+
+## Change rules
+
+- Preserve the `caffy-` and `data-caffy-` HTML vocabulary.
+- Derive API kinds, routes, hierarchy, and page context from Sphinx build-time
+  metadata.
+- Keep behavior changes separate from mechanical refactors and add a regression
+  test for every fixed edge case.
+- Document the license of third-party code or assets added to the repository.
+
+## Required checks
+
+Run these from a clean checkout:
+
+```console
+uv sync --group quality --group test --group package --locked
+uv run --no-sync ruff check .
+uv run --no-sync ruff format --check .
+uv run --no-sync basedpyright
+node --check src/sphinx_caffy/theme/static/caffy.js
+node --check src/sphinx_caffy/theme/static/caffy-axis.js
+uv run --no-sync pytest -m "not browser"
+uv run --no-sync sphinx-build -E -j auto -n -W --keep-going -b html docs docs/_build/html
+uv run --no-sync sphinx-build -E -j auto -n -W --keep-going -b text docs docs/_build/text
+uv run --no-sync python -m build
+uv run --no-sync twine check --strict dist/*
+uv run --no-sync check-wheel-contents dist/*.whl
+```
+
+Visual changes also require the browser contract in Chromium, Firefox, and
+WebKit with `CAFFY_BROWSER_TESTS=1` and the matching
+`CAFFY_BROWSER` value.
+
+## Local preview
+
+Refresh the local preview through the repository script so Sphinx environment
+state and static asset fingerprints are always regenerated:
+
+```console
+mise use uv@latest
+uv run --no-sync python scripts/build_preview.py
+```
+
+The default preview build reuses the Sphinx environment and automatically
+promotes itself to a full rebuild when build-time Python inputs change or a
+source page is removed. Use `--clean` to force a fresh output directory.
+
+## Release
+
+The version source is `src/sphinx_caffy/_version.py`. Keep it aligned
+with the translation catalog's `Project-Id-Version` and the release noted in
+`README.md`.
+
+Tag only after CI passes. Publication also requires the repository variable
+`CAFFY_PUBLISH=true`.
+
+## Security and licenses
+
+Report vulnerabilities privately. Caffy is MIT licensed; Sphinx retains
+its BSD 2-Clause License.

caffy-2026.7.24/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caffy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

caffy-2026.7.24/MANIFEST.in

@@ -0,0 +1,5 @@
+include AGENTS.md
+include LICENSE
+include README.md
+recursive-include src/sphinx_caffy/locale *.po
+prune tests

caffy-2026.7.24/PKG-INFO

@@ -0,0 +1,202 @@
+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).

caffy-2026.7.24/README.md

@@ -0,0 +1,173 @@
+# 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).

caffy-2026.7.24/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["setuptools==83.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "caffy"
+dynamic = ["version"]
+description = "An independent, accessible Sphinx theme for structured library documentation"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [
+  { name = "Caffy contributors" },
+]
+keywords = ["documentation", "sphinx", "sphinx-theme", "python", "api-reference"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Web Environment",
+  "Framework :: Sphinx :: Theme",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Documentation",
+  "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+  "Sphinx>=9.1,<10",
+]
+
+[project.urls]
+Homepage = "https://github.com/Nekch0/caffy"
+Documentation = "https://github.com/Nekch0/caffy#readme"
+Repository = "https://github.com/Nekch0/caffy.git"
+Issues = "https://github.com/Nekch0/caffy/issues"
+Releases = "https://github.com/Nekch0/caffy/releases"
+
+[dependency-groups]
+quality = [
+  "basedpyright>=1.31,<2",
+  "ruff>=0.12,<1",
+]
+build = [
+  "build>=1.2,!=1.5.1,<2",  # 1.5.1 was yanked for breaking changes.
+]
+test = [
+  { include-group = "build" },
+  "beautifulsoup4>=4.13,<5",
+  "myst-parser>=5,<6",
+  "pytest>=8.3,<10",
+]
+package = [
+  { include-group = "build" },
+  "check-wheel-contents>=0.6,<1",
+  "twine>=6,<7",
+]
+browser = [
+  { include-group = "test" },
+  "axe-playwright-python>=0.1.7,<0.2",
+  "playwright>=1.55,<2",
+]
+
+[project.entry-points."sphinx.html_themes"]
+caffy = "sphinx_caffy"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = false
+
+[tool.setuptools.dynamic]
+version = { attr = "sphinx_caffy._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sphinx_caffy = [
+  "py.typed",
+  "locale/*/LC_MESSAGES/*.mo",
+  "theme/*.html",
+  "theme/*.toml",
+  "theme/static/*.css",
+  "theme/static/*.js",
+  "theme/static/*.svg",
+  "theme/static/fonts/*.txt",
+  "theme/static/fonts/*.woff2",
+]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-config --strict-markers"
+testpaths = ["tests"]
+markers = [
+  "browser: cross-browser end-to-end contract tests",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "PERF", "RUF", "S", "UP", "W"]
+ignore = ["S101"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S603"]
+
+[tool.pyright]
+include = ["src", "tests", "docs"]
+exclude = ["docs/_build"]
+pythonVersion = "3.12"
+typeCheckingMode = "standard"

caffy-2026.7.24/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+