Documentation: Framework and Tools#

In creating the Minterpy documentation according to the design principles previously outlined, we treat the documentation as code. Following the docs-like-code framework this means:

  • We write the documentation source files in plain text using a markup language.

  • We store these source files in a version control system, in the same repository as the Minterpy package codebase.

  • We manage the contribution workflow for the documentation similarly to the development workflow, using issue trackers, commits, merge requests, and merge review. Your contributions to the documentation are valued just as highly as your contributions to the codebase.

  • We build the documentation artifacts automatically and publish them online (though you can also build and view them locally).

Documentation generator#

We use the Sphinx documentation generator to build the documentation as HTML files [1] These HTML files can be viewed or deployed (published) as a static website using a hosting service such as Read the Docs or GitHub Pages.

reStructuredText markup language#

Sphinx, by default, uses reStructuredText (reST) as the markup language. Consequently, we write the bulk of the Minterpy documentation in reST, saved in files with an .rst extension.

reST is also used for writing docstrings directly in the Minterpy Python codebase (files with a .py extension) as recommended by PEP 287. This approach allows much of the API Reference to be automatically generated by processing the docstrings in the Python source code.

Jupyter notebooks#

There is, however, a notable exception. Tutorials and how-to guides often include code examples and their outputs (such as texts or plots). Instead of writing these in reST, we use Jupyter notebooks (files with an .ipynb extension). Jupyter notebooks allow us to combine executable code, its outputs, and narrative text in a single document.

During the Sphinx build process, these notebooks are automatically executed, and the outputs are captured and converted into HTML documents to be included in the documentation.

This choice simplifies the documentation writing process and avoids the tedious task of copying and pasting code outputs (including plots) into separate reST files. However, there is a minor caveat: the default markup language for Jupyter notebooks is Markdown, not reST. As a result contributors working across different documentation categories may need to switch contexts.

The good news is that, while less comprehensive, Markdown is easier to learn and write compared to reST. You’re likely already more familiar with Markdown than with reST.

Building and deploying the documentation#

The figure below illustrates the different components and processes involved in building the Minterpy documentation.

../../_images/documentation-tooling.png

Fig. 13 The components, tools, and processes to build and, eventually, deploy the Minterpy documentation online.#

Summary#

There are three types of documents used in the Minterpy documentation source:

  • reStructuredText (reST) files (with an .rst extension)

  • Jupyter notebooks (with an .ipynb extension)

  • Docstrings embedded in the Minterpy Python source code (with an .py extension)

reST files and docstrings are written primarily in reStructuredText markup language, while Jupyter notebooks use Markdown.

Footnotes