Skip to content

Session 3: Documentation and automated workflows

In the last session, we discussed that you should create docstrings as you write your code. In this session, we will talk a bit more about other forms of documentation your project needs.

README page

When we initialised our repository, we added a file called README.md and included a line about what the project was going to be about. Time to flesh this out a bit now that we have more content in our repository. This FreeCodeCamp post contains suggestions of what is useful to include in your README file.

The absolute basics this file should include are:

  1. Project title
  2. Project Description
  3. How to install and run the project
  4. How to use the project
  5. Credits and acknowledgements

We can fill out sections 1, 2 and 5 already, and will get on to 3 and 4 shortly.

Adding other code documentation

In addition to your basic docstrings, you can embed more documentation into your code.

You can add module and package docstrings by adding multi-line comments to the beginning of your Python file and into your __init.py file. This comment can contain top-level information, use examples, and list modules that are exported by the package.

For further information, and to improve your documentation after this course, please read through this RealPython tutorial. You can look at the "Next Steps" section for ideas on how to expand your docs, add code of conduct statements and contributing guidelines, and automate the deployment using GitHub Actions.

Building a documentation website on GitHub pages

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.

Using a GitHub Action to automatically build your documentation

The above workflow requires you to run TZ=UTC mkdocs gh-deploy after you make changes to your documentation. You might instead want to edit locally, test that the website looks correct using the serve option, and then deploy the website online only when changes are merged into the main branch. You can add the following workflow yml file to the folder .github/workflows in order to do this:

# Workflow to automatically deploy mkdocs website when changes are pushed to main
name: mkdocs-action
on:
  push:
    branches:
      - main  # the workflow will run when you push changes to the main branch
  workflow_dispatch:  # you can also manually trigger the workflow for a different branch
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest  # the action runs on a virtual ubuntu machine
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials  # this figures out the permissions
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install \  # install any required mkdocs packages or plugins
              mkdocs-material \
              mkdocs  # you will have to add additional packages if you pip installed any extra features
      - run: mkdocs gh-deploy --force  # make mkdocs deploy even if there already exists content on the gh-pages branch