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:
Ensure that you have a working SciPy Development environment active. You need to be able to
import scipy
regardless of Python’s working directory; thepython setup.py develop
andconda develop
commands from the quickstart guides make this possible.Install Sphinx and matplotlib. For example, if you’re using the Anaconda distribution of Python, enter in a terminal window
conda install sphinx matplotlib
.In a terminal window, browse to the
scipy/doc
directory. Note the presence of the fileMakefile
.Execute
git submodule update --init
. Some of the documentation theme files are not distributed with the mainscipy
repository; this keeps them up to date using git submodules.Enter
make html-scipyorg
. If you have multiple version of Python on your path, you can choose which version to use by appendingPYTHON=python3.7
to this command, wherepython3.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 theMakefile
. 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 withindex.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.