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:
Ensure that you have a working SciPy Development environment active. You need to be able to
import scipyregardless of Python’s working directory; the
python setup.py developand
conda developcommands from the quickstart guides make this possible.
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
In a terminal window, browse to the
scipy/docdirectory. Note the presence of the file
git submodule update --init. Some of the documentation theme files are not distributed with the main
scipyrepository; this keeps them up to date using git submodules.
make html-scipyorg. If you have multiple version of Python on your path, you can choose which version to use by appending
PYTHON=python3.7to this command, where
python3.7is 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.
View the documentation in
scipy/doc/build/html-scipyorg. You can start with
index.htmland 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.