mkdocs workfow

Please first read through this RealPython tutorial.

Ensure you are using a conda environment that has mkdocs and the required additional packages installed (you can install the ready-made mkdocs-env by running conda env create --file .devcontainer/env-files/mkdocs-env.yml and then activating it with conda activate mkdocs).

1. Set up your mkdocs structure

From the main folder of your repository (where your pyproject.toml is), run:

mkdocs new . # initialise a new mkdocs project

This will create both a mkdocs.yml file and a folder docs/ containing an index.md file.

2. Modify your mkdocs yml file

The only required component of the yml is the title field; however, we want to build docs using the docstrings of our functions, and we are using the newer recommended src/package_name layout for our project, so mkdocs needs a bit of help pointing to the correct folders.

site_name: NAME HERE

theme:
  name: "material"

plugins:
- mkdocstrings:
    handlers:
      python:
        paths: [src]  # search packages in the src folder

nav:
  - FILE NAME HERE: index.md

Any additional markdown files placed in the docs/ folder can be added here.

3. Add API reference to your docs

Either create an API reference markdown file in the docs/ folder, or add a section to the index.md file. If you have added sensible and well-formatted comments and docstrings to your code, you can use the mkdocstring plugin to automatically build your documentation.

Simply include:

::: YOUR_PACKAGE_NAME

in one of the markdown files included in your docs to include top-level package notes in your package __init__.py file.

To include function-level documentation, just include:

::: YOUR_PACKAGE_NAME.MODULE_NAME

4. Preview your docs

To serve the docs website locally, just run:

TZ=UTC mkdocs serve # serve the mkdocs website without time zone errors

When you are happy with your documentation content, you can run:

TZ=UTC mkdocs build # build your docs files in a /site dir

to output documentation files, which you can add and commit to your git repository.

5. Publish your documentation

To publish your documentation, switch on GH pages for your repository, and point them to the gh-pages branch. In actions, set actions to have permissions to read and write.

Then simply run:

TZ=UTC mkdocs gh-deploy # deploy the website - change settings on your gh repo to allow writing by actions

to push your changes and publish the documentation on GitHub pages.