Skip to content

Writing documentation

The source of truth is ordinary Markdown under docs/. The website is a rendered view, not a separate body of content.

Local preview

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
zensical serve

Before committing:

zensical build --clean --strict

Page rules

  • Use one # title and sentence-case headings.
  • Prefer short paragraphs, tables for exact mappings, and runnable commands.
  • Use repository-relative links ending in .md; they work on GitHub and are validated by Zensical.
  • Give code fences a language such as python, sh, cmake, or text.
  • State units, coordinate conventions, defaults, and validity limits.
  • Distinguish a low-cost tutorial setting from a production recommendation.
  • Link a model to its primary reference rather than copying a paper summary.
  • Add every public page to nav in mkdocs.yml. Zensical supports this compatibility format, which also keeps the Markdown site portable.

Use standard Markdown before theme-specific syntax. This keeps reviews readable and makes a future site-generator migration inexpensive.

Executable snippets

A command should identify its working repository and prerequisites. Python snippets should use APIs present in the current binding source. When practical, the maintained implementation belongs in hermes-examples; documentation then explains it and links to the script.

Do not maintain two large copies of the same program. Duplicated examples drift quickly and may disagree on units or model selection.

Scientific changes

A documentation-only change can still affect published work. Ask for scientific review when changing:

  • a default parameter or example model;
  • an energy, length, area, solid-angle, or intensity unit;
  • coordinate, HEALPix ordering, or mask semantics;
  • data provenance or citation requirements;
  • convergence or validation advice.

Publishing

The GitHub Actions workflow builds every pull request with strict checking. A push to the default main branch uploads the site/ artifact and deploys it through GitHub Pages.

For a new repository, select GitHub Actions as the Pages source in Settings → Pages. No generated HTML is committed to main.