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.
Examples of documentation websites that we love:
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.
While Sphinx natively supports the
rSTsyntax. 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:
This book is created using Sphinx and the