Metadata-Version: 2.4
Name: heluca-sphinx
Version: 0.2.0
Summary: Heluca Design System theme for Sphinx documentation — the brand layer for the Clio docs estate
Author-email: Robert Helewka <r@helu.ca>
License: MIT
Project-URL: Homepage, https://git.helu.ca/r/heluca-sphinx
Keywords: sphinx,sphinx-theme,furo,documentation,heluca,design-system
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Theme
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Documentation :: Sphinx
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: sphinx<10,>=9.0
Requires-Dist: furo>=2024.1
Provides-Extra: test
Requires-Dist: myst-parser<6,>=5.0; extra == "test"

# heluca-sphinx

The Heluca Design System theme for Sphinx documentation — the brand layer for
the [Clio](https://docs.helu.ca) docs estate. A thin
[Furo](https://pradyunsg.me/furo/)-derived HTML theme that maps the Heluca DS
tokens (amber primary, Marcellus display headings, Literata prose, the
self-hosted DS webfonts) onto Furo's CSS custom properties.

## Usage

Add it to the project's docs dependencies (it publishes to the Gitea PyPI
registry) and select the theme — that's the whole integration:

```toml
# pyproject.toml
[project.optional-dependencies]
docs = [
    "sphinx>=9.0,<10",
    "myst-parser>=5.0,<6",
    "heluca-sphinx>=0.1,<1.0",
]
```

```python
# docs/conf.py
html_theme = "heluca"
```

Install with the registry as an extra index:

```
pip install heluca-sphinx --extra-index-url https://git.helu.ca/api/packages/r/pypi/simple/
```

Selecting the theme is enough — Sphinx loads the module via its
`sphinx.html_themes` entry point, registers the theme directory, and links the
DS stylesheet on top of Furo's. No `html_static_path` copies, no
`html_css_files` list, nothing to drift.

Furo's own options still apply (`html_theme_options` for `light_logo`,
`dark_logo`, `source_repository`, `announcement`, …).

## What it maps

| Surface            | Light (paper)      | Dark (ink)         |
| ------------------ | ------------------ | ------------------ |
| Brand primary      | `#ffa415` amber    | `#ffa415` amber    |
| Content links      | `#4b96ff` blue     | `#58c0ff` blue     |
| Page background    | `#ffffff`          | `#131118`          |
| Sidebar background | `#f4f1ea` paper    | `#17151d`          |

Headings render in **Marcellus**, chrome in **Public Sans**, long-form prose in
**Literata**, code in **JetBrains Mono** — all self-hosted latin `woff2`, no
external font host.

## Provenance

The `@font-face` block and DS token values in
`heluca_sphinx/theme/heluca/static/heluca.css` are **derived** from
[`@heluca/svelte`](https://git.helu.ca/r/heluca-svelte) tokens — the same source
`django-heluca-themis` vendors. They are a committed copy, not a live render:
re-sync both blocks when the upstream tokens change.

## Releasing

Bump `version` in `pyproject.toml`, commit to `main`, then push a matching
bare-version tag (e.g. `0.1.0`). The publish workflow smoke-builds the sample
docs, asserts the theme assets are in the wheel, and uploads to the registry.
