We run peer review of scientific Python software. Learn more.

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.

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:

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:


This book is created using Sphinx and the furo theme.