Rendering Documentation with Sphinx¶
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):
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 sphinxor
conda update sphinx.
In a terminal window, browse to the
scipy/docdirectory. Note the presence of the file
If this is your first time building the docs, execute
git submodule init. After you’ve initialized for the first time, enter
git submodule updateinstead. Some of the documentation theme files are not distributed with the main
scipyrepository; this keeps them up to date with git submodules.
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.
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.