Mallard website
Source of matthewbonanni.github.io/mallard, the website of
Mallard: landing page, gallery, user guide and API reference.
The site is built with MkDocs Material. The documentation pages
and the API reference come from a Mallard checkout at build time, so they match a Mallard release:
docs/guide/ (the user guide), docs/input.md, docs/theory/ (the Theory manual, in the order of its index), docs/numerics/, docs/references.md, docs/design/
(the Developer notes), examples/README.md (Examples, one section per topic), tools/README.md
(Tools) and the Building through Postprocessing sections of README.md (Installation) become the
documentation pages. pages.py assembles them: links written for GitHub become links between the site's
pages (to other files of the repository, links to GitHub at the documented ref; absolute links to this site,
relative ones that --strict checks), and the light/dark figure pairs (#gh-light-mode-only) become
Material's (#only-light). A release without docs/guide/ (0.8.0 and older) is documented with the pages of
Mallard's main, under a note saying so;- Doxygen (with doxygen-awesome-css) generates
docs/api/
from src/ only, with doxygen/mainpage.md as its landing page and doxygen/mallard.css for the brand.
This repository holds what is specific to the site: mkdocs.yml; the home page, gallery, validation page,
documentation landing page and media in content/; content/examples.json (stills and setup diagrams of the
examples); theme overrides in overrides/; build.sh, pages.py; and check_links.py, which build.sh
runs on the built site: links and anchors, alt text of every image and video, and the dark twin of every
light-theme SVG figure (and back). hooks/content.py lazy-loads images and anchors each key's row on the input
reference (<section>--<key>), which content/assets/keys.js scrolls to from a search result. MathJax is served by the site itself: build.sh takes it
from the npm tarball (version and SHA-256 pinned, cached in .cache/) into out/assets/mathjax/.
The Performance dashboard (content/docs/dashboard.md) is drawn at build time by hooks/performance.py from
data/performance.json: the A100 benchmark results of the GPU CI for each merge into Mallard's main, and the
multi-GPU scaling runs. The maintainer regenerates that file from the GPU CI logs with an export script outside
this repository and commits it; it holds only commit and pull request references and the measurements.
validation/ holds the scripts that ran the validation cases and drew the figures in content/validation/
(see the docstring of validation/common.py).
Versions
The site documents Mallard's main branch at its root. build.sh also builds the documentation pages of every
release that has the user guide (docs/guide/) under its own path, e.g. v0.9.0/ (devsite.py adapts a copy of
this repository for each: home, gallery, validation and the API reference link to the root's), so every such
release stays reachable. A selector in the header (content/assets/versions.js) lists main (development) first,
then the releases, newest first, and switching keeps the page. MALLARD_MAIN_REF=<ref> builds another ref as
main, for previews.
Building locally
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt # plus doxygen
git clone https://github.com/MatthewBonanni/mallard.git ../mallard
PATH=$PWD/.venv/bin:$PATH ./build.sh ../mallard # latest release tag
PATH=$PWD/.venv/bin:$PATH ./build.sh ../mallard main # or any ref
python3 -m http.server -d out # site at http://localhost:8000/
Deployment
The pages workflow in the Mallard repository checks out this repository, runs build.sh against the
release that triggered it (or the latest release, when run by hand) and deploys out/ to GitHub Pages.
After changing the site, run that workflow from the Mallard repository's Actions tab.
