What is Sphinx?

Sphinx lets you generate static web pages that can be hosted on sites such as Github Pages and Read the Docs. While there are other tools that can be used to generate documentation, Sphinx is open source, popular, and well-supported.

Some use cases for Sphinx include:

Documenting Code

Sphinx can be used to generate documentation from docstrings. For example: Python’s code documentation.

Knowledge Base

Sphinx can also be used more like a wiki, where reference documents can be hosted in an accessible location.

Blogging

“Blog-style” posts can be integrated into any Sphinx project using the ABlog extension.

Data Visualization

Jupyter notebook visualizations can be embedded into Sphinx documentation using the nbsphinx extension.

Gallery

You can easily throw together a gallery of cards to highlight important features, links, or images. For example, this site.

How do I use Sphinx?

Why reStructuredText (rST)?

This demo assumes you’ll be using rST to write documentation. While there is support for Markdown, the grammar can be cumbersome when writing complicated directives.

Sphinx can be run locally on your laptop to generate HTML files from source code, Markdown, or reStructredText (rST). You can also run it remotely on GitHub by adding a post-commit hook to build documentation pushed to a repository. This will be expanded upon in a later tutorial.

Todo

Add link to tutorial to build docs in GitHub