Add a github action to generate documentation using mkdocs

3 min read | by Jordi Prats

If you have a tool that uses the python's click module for building a command line interface. Using mkdocs and mkdocs-click we can automatically generate documentation for it

First we will have to install mkdocs and mkdocs-click using pip as follows:

pip install mkdocs pip install mkdocs-click 

Using awstools as an example, we'll have to create the following files:

First, the general configuration (/mkdocs.yml)

site_name: awstools theme:   name: readthedocs  navigation_depth: 8  nav_style: dark  collapse_navigation: False docs_dir: docs markdown_extensions:  - mkdocs-click 

To generate pages, we'll need to create the markdown pages that we need. The index page it's going to be (/docs/index.md). For this example we are going to use it to directly hold the documentation we want to generate:

# CLI Reference This page provides documentation for our command line tools. ::: mkdocs-click  :module: awstools  :command: awstools  :depth: 4  :style: table 

We can test it running mkdocs serve, it will listen to 127.0.0.1:8000 so we can see how it will look like:

$ PYTHONPATH=$PWD mkdocs serve INFO - Building documentation... INFO - Cleaning site directory INFO - Documentation built in 0.53 seconds INFO - [19:28:44] Watching paths for changes: 'docs', 'mkdocs.yml' INFO - [19:28:44] Serving on http://127.0.0.1:8000/ (...) 

Finally, we can create github action (/.github/workflows/docs.yaml)to automatically update the documentation on each push to master. We are going to use Github pages for this:

name: build on:  push:  branches:  - main jobs:  deploy:  runs-on: ubuntu-latest  steps:  - uses: actions/checkout@v2  - uses: actions/setup-python@v2  with:  python-version: 3.x  - run: pip install mkdocs  - run: pip install mkdocs-click  - run: pip install -r requirements.txt  - run: export PYTHONPATH=$(pwd)  - run: bash -c "PYTHONPATH=$PWD mkdocs gh-deploy --force --clean --verbose" 

As soon as this action completes, if we have the github pages enabled (check Settings, Pages) we will be able to reach the documentation using an URL based on:

For example, for the awstools repo belonging to jordiprats it is going to be:

https://jordiprats.github.io/awstools/

You can use this commit belonging to the python-matecurses project as an example since it contains all the changes needed for this.

Posted on 14/06/2022