Overview

Documentation is powered by MkDocs with MkDocs Material, hosted on Github Pages. Older docs still exist on the Monorepo's Github Wiki, but it is being migrated to this page.

Setup

For developers, a MkDocs setup is included as part of the dev install script. When working with the documentation locally, remember to activate the venv:

source docs/.venv/Scripts/activate

Otherwise, mkdocs commands will likely not work.

To exit the venv, while in the venv, run

deactivate

Note

For any mkdocs commands, you must be in the outermost docs folder for it to find your files correctly.

Updating

Updating documentation is as simple as updating Markdown files, all contained within the docs folder in the Monorepo.

To preview your changes, this will build the site locally, with automatic updates as you make changes:

mkdocs serve

Deploying

With Github Actions, updates to the main branch will automatically build and deploy the static site to the gh-pages branch.

To deploy manually, run

mkdocs gh-deploy --force

This updates the gh-pages branch with the static site. Keep in mind, if there are unpublished changes, it will display those changes as well, so beware!

To preview what files will be generated and published, this generates the static website files under docs/site/:

mkdocs build

Notes

There are many MkDocs Plugins that may be useful while updating documentation, so consider them as this documentation evolves! More information about plugins here.

The Github Action for automatic deployment was found here, slightly changed.

If time allows for it, consider looking at Sphinx instead, for documentation. It seems more advanced, with more features and apparently better code integration with documentation, but may be harder to set up and learn.