Sphinx primer for ArviZ and PyMC contributors

Fig. 1 Sphinx is a documentation generator.

Sphinx takes raw text content written with a markup language, and it translates and renders it in an rich output format such as html or pdf.

The native markup language in Sphinx is rST, however, it is also possible to use MyST, a superset of markdown thanks to the executablebooks project.

Fig. 2 outlines the process by which sphinx generates documentation. Don’t worry if things don’t make much sense yet. The key concept will be explained as they are needed and references to further reading will also be provided in the coming pages.

Fig. 2 Documentation generation process with Sphinx.

ArviZ and PyMC use both rST and MyST, which can be combined without problem within the same documentation, but the bulk of the content is written in MyST, with rST being used nearly exclusively for docstrings.

Why MyST? MyST is a markdown superset, therefore pure markdown is also valid MyST. Markdown is the most common markup language nowadays and both developers and users of ArviZ and PyMC are familiar with it from sites like GitHub or Discourse. Moreover, markdown is the markup language used in Jupyter notebooks. Using MyST also allows us to work indistinctively in .md or .ipynb files.