Sphinx

Note

This page was written in the style of an Explanation according to The Diátaxis Framework.

What is Sphinx?

Sphinx is a documentation generator that converts reStructuredText (RST) files to formats like HTML, LaTeX, ePub, Texinfo, manual pages or plain text. It is written in Python. Some of its main characteristics are:

  • Ability to cross-reference to pages corresponding to functions, classes, attributes, parameters and similar, creating links with semantic markup.

  • Intuitive hierarchical structure for documentation trees.

  • Index pages generated automatically.

  • Automatic code highlighting with Pygments.

  • Customizable HTML themes.

Why do we use Sphinx in Qiskit?

One of the main reasons we use Sphinx is that it creates API reference pages automatically from the Python code, which makes up most of Qiskit’s code, so documentation is easier to create and mantain. Apart from that, Sphinx allows you to cross-reference to pages inside the documentation instead of using the URL from the deployed page, so you reduce the risk of broken links to a minimum when parts of the documentation are moved to a different place.

Sphinx also offers a wide array of extensions that make creating docs much easier, like the following:

  • intersphinx, that enables you to link to other projects, like other Qiskit repositories.

  • napoleon, that lets you use NumPy and Google style docstrings, simpler than using pure RST.

  • autodoc, that automatically creates module pages.

  • autosummary, that creates summary tables for functions, methods, attributes or parameters from their source code, avoiding duplication of content.

  • reno.sphinxext, that incorporates release notes to the documentation automatically.

  • jupyter_sphinx, that allows you to run Jupyter cells.

Another Sphinx characteristic we use extensively is the ability to customize an HTML theme, so we have our own theme called qiskit_sphinx_theme, that gives a consistent theme for projects in the Qiskit Ecosystem.