cayman-sphinx

A Sphinx HTML theme styled after GitHub Pages' classic Cayman theme: a single-column page with a gradient hero banner — logo, tagline, and buttons generated from a hidden toctree — plain, readable body typography, and a simple footer. No sidebar.

It's generic and reusable: the theme reads standard Sphinx config (html_logo, project, a hidden toctree, and html_context.github_user / github_repo), so adopting it usually means changing a single line in conf.py.

Install

pip install cayman-sphinx

Or from a checkout of this repository:

pip install .

Use

In your project's conf.py:

html_theme = "cayman_sphinx"
html_theme_options = {
    "description": "a short tagline shown under the logo",
}

The theme registers itself with Sphinx through an entry point, so there is no html_theme_path to configure.

What the theme reads

The hero banner and footer are assembled from configuration you likely already set:

Sphinx config	Used for
html_logo	Logo in the hero (falls back to project as a title)
project	Title text and footer owner label
html_theme_options["description"]	Tagline under the logo
a hidden toctree in your root document	The row of hero buttons (one per entry)
html_context["github_user"] / github_repo	Footer "maintained by" links
color theme option	Accent color (default #2980b9)

Because the buttons come from a hidden toctree, you control them from your index.rst with no theme-specific markup, e.g.:

.. toctree::
   :hidden:

   Read the Docs <https://example.com/docs>
   GitHub <https://github.com/octocat/hello-world>

Demo

demo/ vendors PyRTL's actual www/ homepage source (from UCSBarchlab/PyRTL, BSD-3-Clause) so the theme can be checked against real content. It is not part of the installable package. Build it with:

uv run sphinx-build -M html demo demo/_build
# then open demo/_build/html/index.html

Development

uv run pytest          # run tests
uv run ruff check .    # lint
uv run ruff format .   # format
uv run mypy src/       # type check

License

BSD 2-Clause © 2026 Timothy Sherwood. The vendored PyRTL demo content under demo/ is BSD-3-Clause, © its respective authors.