Skip to content

05 - Python documentation with mkdocs

Diàtaxis framework

  • Tutorials: Learning-oriented
  • How-to-Guides: Problem-oriented
  • Reference: Information-oriented
  • Explanation: Understanding-oriented

mkdocstrings

This package is responsible to scan python code and convert it into markdown for documentation. Here it is its gituhub repository

PEP-257: Docstring conventions

This is a helpful reference to make sure the conventions and best practices are being followed in the development of python documentation. Look at it here

doctest

You can write tests directly in your docstrings. Here it is an example:

def add(a: int, b: int):
    """
    Return the sum of two integers.

    >>> add(3,2)
    5
    >> add(9,-1)
    8
    """

You can run the doctests by typing

python -m doctest <PATH TO THE DOCTEST FILE>
Info

Every reasonable format can be passed to the doctest executable. That includes .py of course, but also .md.

When to use

You can't easily create any type of test with doctest, so you should limit its use to reasonable cases. I am considering the following:

  1. Unit test of utilities and base functions.
  2. Tests that are located in documentation files of types: 'How-to guides' and 'Tutorials'.

Directives

  • #doctest: +ELLIPSIS
  • #doctest: +NORMALIZE_WHITESPACE
Hint

When checking if exceptions are raised, you don't need to explicitly write the ELLIPSIS directive. You can literally write the ellipsis ... and doctest will interpret that as a placeholder for garbage. E.g.

    >>> add(1, "bzik") 
    Traceback (most recent call last):
    ...
    TypeError: unsupported operand type(s) for +: 'int' and 'str'

Debugging

I didn't dig too much on this topic, but it seems interesting.

Integrating with mkdocs

plugins:
    - mkdocstrings

Integration with GitHub Pages

A handy feature of mkdocs is that you can call mkdocs gh-pages to build your documentation and automatically set your repository with a gh-pages branches which is automatically recognized by github pages.

GitHub Actions

This feature allows to create CI/CD workflows in GitHub. I've created one for my python projects.

The reference workflow is the one in toml-dataclass. For this workflow I also created the action setup-python-project-environment-action.

This workflow executes all the tasks I usually execute to test the code during development (via tox tasks). It relies on a specific hierarchy structure that I use for my Python projects. The final step of the workflow is to build the sphinx documentation that is automatically deployed to a dedicated page hosted by GitHub pagaes.

This first experience with GitHub actions was chaotic. A mix of reading the documentation plus a try and error process that generates a lot of commits in my repositories (properly cleaned with a rebase). After I succeeded running the workflow, I started to look for tools that could help me with testing the actions locally. I found it act.

References

Exercises

  • Write about my experience with github-actions.
  • Read 2 documentation articles from github actions.
  • Update the docstrings of toml_dataclass following the PEP-257 guidelines.
  • Add doctest to some of the docstrings of toml_dataclass.
  • Add some doctest in the README.md of toml_dataclass and call doctest on it as part of the test pipeline.
  • Add doctest in the docstring of modules. It accepts markdown format. (Look at PEP-257 for reference).
  • Look at alternatives of debugging in python.