Skip to content

Chapter 8: Authoring and maintaining documentation

Some quick philosophy on documentation

  • The Diátaxis framework provides guidelines to create effetive documentation. According to it, we should create several documentation style in the same project, each one targeting at a different need of the user.

  • Tutorials: Helps a new comer to discover the general ideas and get started with the project;

  • How-tos: Provides help to a specific task;
  • Discussions: Helps the reader to understand the history and decisions in a project;
  • Reference: Helps the reader with very specific information such as syntax.

Automating extraction of code documentation

Important

The book uses Sphinx as documentation engine. An alternative is MkDocs. To use with Python you may want to install the plugin: https://github.com/pawamoy/mkdocstrings. This will allow you to convert python docstrings into documentation.

  • To extract python docstrings and convert it into reStructured Text, you should use the sphinx-apidoc command. This command comes with sphinx already, together with sphinx-build and sphinx-autobuild. Later, you should reference the output directory of sphinx-apidoc in the index.rst file.
Important

The sphinx-apidoc command relies on code contained in the sphinx.ext.autodoc extension. You should activate this extension in the config.py file in order to call sphinx-apidoc.

  • Use sphinx-autobuild to let sphinx automatically render your documentation as soon as a change in your documentation files is detected.

  • In the config.py file you can specify the documentation version such that it is in sync with your pyproject.toml version. You should use the importlib.metadata package for that.

Hint

I am currently using a custom GitHub Action to push a new documentation build to the gh-pages branches. That way, my projects documentation are hosted in my personal page. An alternative would be to set tup ReadTheDocs. It seems fairly easy to use.

Publishing documentation to Read the Docs

  • It offers an web-interface to configure sphinx documentation build directly from git repositories.
  • Your projects must be open-source to use ReadTheDocs for free.
  • If you are extracting docstrings with sphinx-apidoc you need extra configuration to instruct the ReadTheDocs builder to execute the sphinx-apidoc command.
  • ReadTheDocs reads the .readthedocs.yaml file from your repository root directory. It has a structure similar to GitHub actions files.
  • We need to run sphinx-apidoc before sphinx-build. That's what we are doing in our tox task. But readthedocs is not aware of our tox commands. In fact, readthedocs will only execute the sphinx-build command.
  • In order to call sphinx-apidoc we need to add some code in the sphinx documentation config.py file.

Configuring sphinx-apidoc to run in ReadTheDocs environment

  • In the ReadTheDocs interface you can also configure it to run at every pull-request or some other github event.

Documentation best practices

  • Prefer linking over repetition. Consider using the intersphinx extension.
  • Use consistent and empathetic language. Tenses should be consistent; Grammar should be correct. Stick to the facts and remove weasel words such as: "it is easy to see that" or "in a few simple steps".
  • Avoid assumptions and create context. If prior knowledge it is necessary to read a section of the documentation, make sure that the requirements are explicitly listed and linked.
Hint

If you want to use Markdown within Sphinx, take a look at MyST