Skip to content

Documentation

Project documentation lives in /docs and is written in Markdown.

For web-based access, these files are passed through a static site generator MkDocs, specifically MkDocs Material and served via Github Pages.

Development

You can run a live-reloading web server in imitation of the production generator. To do so:

  • Ensure that your python environment is using python3 and its package manager pip3. You can then install the required mkdocs executable and its dependencies using: 
    1
    python -m pip install -r requirements-mkdocs.txt
  • Run mkdocs serve from the project root. A convenience Make command is likewise provided as make mkdocs-serve.
  • Open http://localhost:8000 in a web browser.
  • Write some docs!

docs/img/logo.svg is the master for the site’s logo, and the header shows it directly. PNG renderings are made from it and never edited by hand. The favicon is rendered with Inkscape, from the project root:

1
inkscape docs/img/logo.svg --export-type=png --export-width=64 --export-filename=docs/img/favicon.png