# Rendering Documentation with Sphinx

SciPy docstrings are rendered to HTML using Sphinx and the PyData Sphinx theme. Writing docstrings is covered in the A Guide to NumPy 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:

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

1. Install Sphinx, PyData Sphinx theme, Sphinx-Panels 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 matplotlib --channel conda-forge`. The list of requirements is in `scipy/doc_requirements.txt`.

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

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

4. 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.7` to this command, where `python3.7` 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.

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.

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

PEP8 and SciPy Running SciPy Tests Locally