Documentation

With Python, as with many other languages, it’s very common to automatically create a web page with documentation. This can include reference for the API taken from your package’s docstrings, tutorials, examples, and more in depth explanation about how the package works. For an in-depth discussion of the different components of good documentation, see the Diátaxis framework. For your package to be easily reusable we recommend you build documentation pages and host them somewhere.

If you’re using GitHub, one option is to host your docs on GitHub pages. Here’s how we’ve set this up for our template.

Documentation build tools

Name Short description 🚦
MkDocs Generates documentation from Markdown files, with a plugin to generate API documentation. A good plugin ecosystem and balance of usability and customisability. 🟢
Sphinx Generates documentation from reStructuredText or Markdown files, long been the de-facto standard and very widely used. Mature plugin ecosystem. 🟠
gitbook General documentation builder; integrates with GitHub. 🟠
pdoc Auto-generates API documentation from docstrings, beginner friendly but with less of a plugin ecosystem than others. 🟠
More details about Sphinx

We marginally recommend MkDocs over Sphinx due to it’s ease of use, preference for Markdown, and more support for a variety of docstring styles.

However the Sphinx tool has long been the de-facto standard in the scientific Python ecosystem. It is widely used, customisable, and well tested. If you need a Sphinx extension that does not have an equivalent MkDocs plugin, or if you are part of a community that heavily uses Sphinx then we recommend you use that instead.

See also

MkDocs plugins

Name Short description 🚦
mkdocstrings-python Automatically generates API reference pages. 🟢

Sphinx extensions

Name Short description 🚦
sphinx-gallery Builds an HTML gallery of examples from a set of Python scripts. 🟢
sphinx-autoapi Automatically generates API reference pages. 🟢