To build the html docs for local development, SciPy itself needs to be built so your environment needs to be set up for that. For details on that, see the Contributor Guide).
Also ensure to initialize and update submodules (this pulls in the SciPy Sphinx
theme and numpydoc):
git submodule update --init
Now to build both SciPy itself and the docs, use:
python3 runtests.py --doc html
Alternatively, if you prefer to build SciPy and the docs separately rather
than use runtests.py:
python setup.py develop # in the root of the repo
cd doc && make html-scipyorg
In case the SciPy version found by the above command is different from that of the latest commit in the repo, you will see a message like:
installed scipy 5fd20ec1aa != current repo git version '35fd20ec1a'
This indicates that you're likely picking up the wrong SciPy install, check
with python -c "import scipy; print(scipy.__file__)".
If the build is successful, you can open it in your browser with make show
(which will open build/html-scipyorg/index.html).
To build the pdf docs, which requires a LaTeX install and can be more fiddly to get to work, replace the doc build commands in the section above with:
python3 runtests.py --doc latex
or:
make latex
That will use Sphinx to generate the LaTeX sources. To then produce a pdf,
navigate to doc/build/latex/ and run:
make all-pdf
That will produce a file scipy-ref.pdf in build/latex/.
For building all the documentation artifacts for a release, run:
make dist
This will build SciPy in-place (to ensure the version is correct), build html and pdf docs as well as create a zip archive of the html docs that can easily be redistributed.
sourceis where most of the content lives.devcontains the contributor and developer guides as well as the governance docs and the code of conduct.tutorialcontains all tutorial content.
releasecontains the release notes. Note that those normally should not be updated as part of a PR; we keep releases notes for the upcoming releases on the wiki of the main SciPy repo.