Documentation#

The docs are built with Sphinx and the Shibuya theme, and written in MyST Markdown.

$ uv run --extra doc sphinx-build -b html docs docs/_build/html
$ uv run --extra doc sphinx-build -E -W -b html docs docs/_build/html   # clean, warnings as errors

Use -E after changing anything in docs/_ext/ or docs/_examples/; Sphinx only re-reads pages whose source changed.

Publishing#

The site is static HTML, served from bunny.net. A GitHub Actions workflow builds it with -W and uploads docs/_build/html/ as it is; no server-side processing is needed. The KaTeX stylesheet and fonts load from jsDelivr, so math needs no extra files.

Two environment variables affect a published build:

Variable

Effect

HC_SOURCE_REF

The git ref that source links point at (see Source links).

HC_DOCS_URL

The site’s root URL, used for canonical links. Defaults to https://handcalcs.structuralpython.com/.

Layout#

Path

Contents

docs/conf.py

Configuration, including HC_SOURCE_REF (see below) and the theme’s navigation bar.

docs/index.md

The landing page.

docs/<section>/index.md

Each section’s first page: the short “what you need to get going” page, with cards to the rest of the section.

docs/_ext/

Local Sphinx extensions: hc_example.py, hc_source.py.

docs/_examples/

Example renderers used by the docs; each is run by the build.

docs/_static/handcalcs-docs.css

Styles for the live examples.

Writing pages#

Each section follows the same layered structure, so readers always know where to look:

  1. The section index gets someone going: the common task, one example, then a grid of cards to the other pages.

  2. Topic pages cover one task or concept fully, and end with a “Next” link.

  3. The reference holds exhaustive tables and the API.

Start pages with what the reader can do, show a working example early, and link to the reference rather than repeating it.

Live examples: hc-example#

```{hc-example}
:renderer: markdown
a = 2
b = 3
c = 2*a + b/3
```

The directive runs the code, renders it, and shows the source followed by the output. The output is shown according to the renderer: Markdown is parsed (so math is typeset), HTML is embedded, everything else is a code block.

Option

Meaning

:renderer:

A registered renderer name (default markdown).

:renderer-file:, :renderer-class:

A file in docs/ defining a renderer, and the class (or factory function) to call.

:output:

code, markdown, html or none, to override the default.

:output-language:

Highlighting for a code output.

:hide-source:

Show the output only.

:setup:

Code run before the example but not shown (e.g. from math import sqrt).

:caption:

Replaces the “Output (Renderer)” label.

Examples are rendered with handcalcs’ built-in defaults, never a builder’s saved config. Prefer hc-example to a hand-written output block wherever handcalcs can produce the output, so the docs cannot drift from the code.