Rendering Documentation with Sphinx#

SciPy docstrings are rendered to HTML using Sphinx and the PyData Sphinx theme. Writing docstrings is covered in the Documentation style; this document explains how to check that docstrings render properly.

For a video walkthrough, please see Rendering SciPy Documentation with Sphinx .

Rendering Documentation Locally#

To render the documentation on your own machine:

  1. Ensure that you have a working SciPy Development environment active. You need to be able to import scipy regardless of Python’s working directory; the python setup.py develop and conda develop commands from the quickstart guides make this possible.

  2. Install Sphinx, PyData Sphinx theme, Sphinx-Panels, Sphinx-Tabs and matplotlib. For example, if you’re using the Anaconda distribution of Python, enter in a terminal window:

    conda install sphinx pydata-sphinx-theme sphinx-panels sphinx-tabs matplotlib --channel conda-forge

    The list of requirements is in scipy/doc_requirements.txt.

  3. In a terminal window, browse to the scipy/doc directory. Note the presence of the file Makefile.

  4. Execute git submodule update --init. Some of the documentation theme files are not distributed with the main scipy repository; this keeps them up to date using git submodules.

  5. Enter make html-scipyorg. If you have multiple version of Python on your path, you can choose which version to use by appending PYTHON=python3.9 to this command, where python3.9 is to be replaced with the name of the Python you use for SciPy development. This uses the Make build automation tool to execute the documentation build instructions from the Makefile. This can take a while the first time, but subsequent documentation builds are typically much faster.

  6. View the documentation in scipy/doc/build/html-scipyorg. You can start with index.html and browse, or you can jump straight to the file you’re interested in.

Note

Changes to certain documents do not take effect when Sphinx documentation is rebuilt. In this case, you can build from scratch by deleting the scipy/doc/build directory, then building again.

Checking Documentation on the Cloud#

Once a PR is opened, you can check that documentation renders correctly on the cloud.

  1. Log in to GitHub.

  2. Log in CircleCI using your GitHub account.

  3. Back in GitHub, at the bottom of the PR, select “Show all Checks”.

  4. Next to “ci/circleci: build_docs artifact”, select “Details”.