Editing and building this documentation

This documentation is written using markdown, with special extensions that are supported by zensical. Zensical is the successor to mkdocs and mkdocs-material. We use zensical rather than mkdocs/mkdocs2 as mkdocs is deprecated and mkdocs2 breaks a lot of backwards-compatibility.

Installing zensical

You need zensical to build the documentation and use all its features. Without zensical, mhttpd can still show most of it, with a simpler built-in renderer. See Serve the documentation through mhttpd.

As well as regular zensical, we have custom code for generating API documentation from the C++/python/web source code. This code is the mkdocstrings-midas package in $MIDASSYS/doc/mkdocs/mkdocstrings-midas. Installing it also installs zensical and the other packages needed to build the documentation.

The package isn't part of the midas Python package, because only people who build the documentation need it. Install it as editable (-e), so that changes to its code are used without reinstalling it.

pip install -e "$MIDASSYS/doc/mkdocs/mkdocstrings-midas"

brew install python uv

uv tool install \
  --no-managed-python \
  --with-editable "$MIDASSYS/python" \
  --with-editable "$MIDASSYS/doc/mkdocs/mkdocstrings-midas" \
  zensical

zensical --version

sudo apt update
sudo apt install --yes ca-certificates curl python3
curl -LsSf https://astral.sh/uv/install.sh | sh

export PATH="$HOME/.local/bin:$PATH"

uv tool install \
  --python /usr/bin/python3 \
  --no-managed-python \
  --with-editable "$MIDASSYS/python" \
  --with-editable "$MIDASSYS/doc/mkdocs/mkdocstrings-midas" \
  zensical

zensical --version

pip install -U --upgrade-strategy eager -e "$MIDASSYS/doc/mkdocs/mkdocstrings-midas"

uv tool upgrade zensical

Building the documentation

You can choose to build a version that is served via a webserver (written to $MIDASSYS/doc/mkdocs/html_web), or one that is completely static (written to $MIDASSYS/doc/mkdocs/html_local).

Serve via a web server

To build docs and serve via a webserver:

cd $MIDASSYS/doc/mkdocs
zensical build -c -f web.yml && zensical serve -f web.yml

Navigate to http://localhost:8000/zensical/

Build a static site

The static site does not require a web server to be running, but misses a couple of features (notably instant previews and links to edit the page).

To build docs and generate a completely static site:

cd $MIDASSYS/doc/mkdocs
zensical build -c -f local.yml

Open $MIDASSYS/doc/mkdocs/html_local/index.html in your browser

Build with CMake

You can also build the static site as part of the normal MIDAS build. First install Zensical and its plugins, then enable the MIDAS_BUILD_DOCS option, which is off by default:

cd "$MIDASSYS"
cmake -S . -B build -DMIDAS_BUILD_DOCS=ON
cmake --build build

The documentation step runs after the other default build targets finish, including during parallel builds. To build only the documentation, use cmake --build build --target docs.

Alternatively, build the documentation independently of the MIDAS programs:

cd "$MIDASSYS"
cmake -S doc/mkdocs -B build-docs
cmake --build build-docs

Both methods generate $MIDASSYS/doc/mkdocs/html_local/index.html and set MIDASSYS to the checkout being built for the API documentation handlers. If Zensical is missing from PATH, the documentation step prints a short notice and skips building the HTML. You can select another installation by adding -DZENSICAL_EXECUTABLE=/path/to/zensical to the CMake configuration command.

Every build calculates a SHA-256 fingerprint of all .md filenames and contents under doc/mkdocs/md/. Zensical runs on the first build, when that fingerprint changes, or when the saved fingerprint or html_local/index.html is missing. The fingerprint is saved in html_local/.midas-docs-state only after a successful build; failed builds are retried on the next build.

Local Markdown edits, additions, deletions and renames trigger a rebuild without requiring a commit. Git revisions and file timestamps are not checked, so a git pull that leaves the Markdown unchanged does not trigger a rebuild. Changes to other inputs, such as configuration, images, API source code or installed tools, require a forced rebuild:

cmake --build build-docs --target docs-force

For the main MIDAS build, replace build-docs with build. The manual Zensical commands above remain available, but do not update the saved CMake fingerprint.

Serve the documentation through mhttpd

The Documentation page of the web interface shows this documentation inside mhttpd, so that it matches the installed version of midas. Open it at ?cmd=Documentation (or /docs), or with the Documentation menu entry, which is hidden by default. To open a given page, add its path, e.g. ?cmd=Documentation&path=reference/reference/odb_keys.md.

mhttpd looks for the documentation in doc/mkdocs below three places, in this order: its current directory, the experiment directory and $MIDASSYS. How the pages are shown depends on whether the static site has been built:

• Static site built (html_local/index.html exists): mhttpd serves the pages from html_local, and the Documentation page shows them in a frame. They look and work the same as when you open the static site from disk. Build it as described in Build a static site
• No static site: mhttpd uses a custom Markdown-to-HTML renderer. This works without zensical, but has limitations (see below). mhttpd serves the Markdown files from md, and the Documentation page renders them in the browser with resources/markdown.js. The navigation is read from the nav in common.yml

So the Documentation page always works, but it looks best if you build the static site after updating midas:

cd $MIDASSYS/doc/mkdocs
zensical build -c -f local.yml

The files mhttpd serves for the documentation are:

Versioned documentation on midas.triumf.ca

https://midas.triumf.ca/docs/ has the documentation for the develop branch and for each release of midas (but only releases since the new documentation was created). A version menu at the top of each page switches between them. Only the docs server needs to build this. Everyone else builds a single version, as described above.

The versioned site is built with mike (a fork of mike for zensical), using two files in doc/mkdocs:

build_versioned_docs.sh develop            # update the develop docs
build_versioned_docs.sh midas-2026-08-a    # add a release, and make it the latest

On the docs server, cron updates the develop docs every night. Releases are added by hand.

The settings (such as the directories and the backup repository) are described in the comments at the top of build_versioned_docs.sh.

How this documentation is organised

The documentation is organised by feature, not by audience. The audience of each page is shown by its tags (Operator, Admin, Developer, Reference, API, Internals).

Top-level sections

Features, Reference, API and each feature folder start with an index.md, which the section header in the navigation links to. Getting started has no index.md: its first page is What is midas.

Pages within a feature

Each feature uses only the pages it needs from this list, in this order:

Small features are a single page. Page titles always include the feature name, so that search results are easy to tell apart. The page's H1 matches its title. In the nav of common.yml, the label is the title without its <Feature>: prefix (e.g. Overview for "ODB: overview"), because the feature's name is already shown above it.

Where does this go?

1. A fact that someone looks up (an ODB key, a command-line option, a function signature, a status code, a limit) goes in Reference (or API, for function signatures), and only there. Other pages link to it.
2. Anything that needs code to be compiled or run goes on the feature's programming page.
3. Changing settings, deploying, and fixing or recovering things go on the feature's configuring page.
4. Everything else an operator needs (concepts and day-to-day operation) goes on the feature's overview page.
5. How midas works inside, when the reader doesn't need it to use the feature, goes in Internals.

Reading order

Features are ordered so that the documentation can be read from start to finish: a feature comes after the features it depends on. If a page needs a concept from a later feature, give a one-line explanation and a link at the first mention.

Related pages

End each feature overview that has configuring or programming pages with a "Related pages" abstract admonition with the extra related class, containing links separated by single spaces, each starting with an icon. The spacing between links comes from the .admonition.related rule in extra.css. Group the links as Configuring, then Programming, then Reference. A group may have several links, and groups with nothing relevant are left out. Other pages can use the same block where it helps.

!!! abstract related "Related pages"
    [:lucide-settings: Configuring](configuring.md) [:lucide-code: Programming](programming.md) [:lucide-book-marked: ODB keys](../../reference/reference/odb_keys.md) [:lucide-book-marked: odbedit](../../reference/reference/programs.md#odbedit)