Using Sphinx to Build Python Package Documentation

On this page we discuss using Sphinx to build your user-facing package documentation. While Sphinx is currently the most commonly-used tool in the scientific Python ecosystem, you are welcome to explore other tools to build documentation such as mkdocs which is gaining popularity in the Python packaging ecosystem.

Tip

Examples of documentation websites that we love:

• GeoPandas

  • View rst to create landing page

• verde

  • View verde landing page code - rst file.

• Here is our documentation if you want to see a myST example of a landing page.

Sphinx - a static site generator

Sphinx is a static-site generator. A static site generator is a tool that creates html for a website based upon a set of templates. The html files are then served “Statically” which means that there is no generation or modification of the files on the fly.

Sphinx is written using Python.

Sphinx sites can be customized using extensions and themes

The functionality of Sphinx can be extended using extensions and themes. A few examples include:

• You can apply documentation themes for quick generation of beautiful documentation.

• You can automatically create documentation for your package’s functions and classes (the package’s API) from docstrings in your code using the autodoc extension

• You can run and test code examples in your docstrings using the doctest extension

• While Sphinx natively supports the rST syntax, you can add custom syntax parsers to support easier-to-write syntax using tools such as the MyST parser.

Commonly used Sphinx themes

You are free to use whatever Sphinx theme that you prefer. However, the most common Sphinx themes used in the Python scientific community include:

• pydata-sphinx-theme

• sphinx-book-theme

• furo

Tip

This book is created using Sphinx and the furo theme.