Rendering Documentation with Sphinx

SciPy docstrings are rendered to html using Sphinx. Writing docstrings is covered in the A Guide to NumPy/SciPy Documentation; 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 (macOS or Linux):

  1. Install Sphinx or ensure that your installation is up to date. For example, if you’re using the Anaconda distribution of Python, enter in a terminal window conda install sphinx or conda update sphinx.

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

  3. If this is your first time building the docs, execute git submodule init. After you’ve initialized for the first time, enter git submodule update instead. Some of the documentation theme files are not distributed with the main scipy repository; this keeps them up to date with git submodules.

  4. Enter make html-scipyorg. 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. Note: If you use a virtual environment for development, activate it first.

  5. 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.


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”, select “Details”.

  5. Select the “Artifacts” tab and find index.html.