Skip to content

Documentation

Generation

Our docs are configured to be rendered by the static site generator MkDocs with the beautiful Material for MkDocs theme.

Plugins

We use a select few MkDocs plugins to achieve the following:

  • minify HTML ()
  • display the date of the last Git modification of every page ()
  • automatically generate docs based on code and docstrings ()
  • export the site as a PDF ()

Extensions

We also depend on a few Python-Markdown extensions to achieve the following:

  • support for emojis, collapsible elements, code highlighting, and other advanced features courtesy of the PyMdown extension suite ()
  • ability to inline SVG icons from Material, FontAwesome, and Octicons ()
  • allow arbitrary scripts to modify MkDocs input files ()
  • automatically generate reference docs for Click-based command line interfaces ()

References

All references are automatically available to all pages.

Abbreviations

These allow for the expansion of text on hover, useful for acronyms and definitions.

For example, if you add the following to the list of abbreviations:

*[CERN]: European Organization for Nuclear Research

then anywhere you type CERN the organization's full name will appear on hover.

All links to external resources should be added to the list of external links rather than defined on a per-page basis, for many reasons:

  1. it keeps the Markdown content compact and thus easy to read and modify
  2. the ability to re-use a link, even if you forsee no immediate use elsewhere
  3. easy automation of stale link detection
  4. when links to external resources change, the last date of Git modification displayed on pages will not

Scripts

We use some scripts to dynamically modify pages before being processed by other extensions and MkDocs itself, to achieve the following:

Build

We define a hatch environment called docs that provides all the dependencies necessary to build the documentation.

To build and view the documentation in your browser, run the serve command (the first invocation may take a few extra moments):

ddev docs serve

By default, live reloading is enabled so any modification will be reflected in near-real time.

Note: In order to export the site as a PDF, you can use the --pdf flag, but you will need some external dependencies.

Deploy

Our CI deploys the documentation to GitHub Pages if any changes occur on commits to the master branch.

Danger

Never make documentation non-deterministic as it will trigger deploys for every single commit.

For example, say you want to display the valid values of a CLI option and the enumeration is represented as a set. Formatting the sequence directly will produce inconsistent results because sets do not guarantee order like dictionaries do, so you must sort it first.

Last update: March 7, 2024