These instructions assume:
# Create a fresh environment with python 3.8. # Ignore the "ncurses" message. conda create --name doc-build-38 python==3.8 # Switch to the new environment conda activate doc-build-38 # Install Cython conda install Cython # Build/install NumPy 2>&1 pip install -e . | tee pip_install.log # Install additional requirements for the docs 2>&1 pip install -r doc_requirements.txt | tee pip_install_doc_req.log # Install additional sphinx dependencies that are included as submodules cd doc git submodule update --init # You're now ready to build the docs. # To preview your changes after you've edited the .rst, you'll rerun this step. 2>&1 make html | tee make_html.log
Thanks to @rossbar for providing and commenting these steps.
tee commands are optional (for instance, you can just run
pip install -r doc_requirements.txt), but it’s helpful to have a log – particularly for the HTML build.
build succeeded. The HTML pages are in build/html. python3.8 postprocess.py html build/html/*.html Build finished. The HTML pages are in build/html.
Be alert to “successes” where nothing got built (perhaps you forgot to save your changes):
Build finished. The HTML pages are in build/html. no targets are out of date.
make html appears to run to completion, but the final message is something like:
build finished with problems, 10 warnings. Makefile:179: recipe for target 'html-build' failed make: *** [html-build] Error 1
Grep the log for
WARNING; for example:
/home/bjn/numpy_git/numpy-1/doc/source/dev/gitwash/development_setup.rst:106: WARNING: Bullet list ends without a blank line; unexpected unindent.
If you see inexplicable warnings from a file you haven’t changed, assume something’s gotten corrupted; run
make html may fail immediately with:
$ make html installed numpy e84f49e62d != current repo git version '5345c2575a' use "make dist" or "GITVER=e84f49e62d make html ..." Makefile:93: recipe for target 'version-check' failed make: *** [version-check] Error 1
The fix is to go up a level (that is, from doc to numpy) and reinstall numpy by rerunning
pip install -e . This is time-consuming because after the reinstall
make html will rebuild from scratch. A workaround is to set
GITVER as indicated, but before you submit the PR ensure your doc and environment is clean by doing the reinstall and rebuild.
Even after what looks like a successful NumPy rebuild:
$ 2>&1 pip install -e . | tee pip_install.log ... Successfully installed numpy
you may see a message like this when you
$ make html numpy not found, cannot build documentation without successful "import numpy" Makefile:90: recipe for target 'version-check' failed make: *** [version-check] Error 1
This means the installed numpy isn’t working, as you can verify by seeing if a traceback occurs when you run
$ python -c 'import numpy as np'
The docs build may fail with
ImportError: Something is wrong with the numpy installation. While importing we detected an older version of numpy in ['/home/bjn/numpy_git/numpy-1/numpy']. One uninstall numpy until none is found, then reinstall this version.
NumPy should always build cleanly if you’ve pulled the master branch from the server. Assume any error is due to a corrupted install; remove the numpy install and rebuild NumPy.
In the top level (above docs), delete the numpy directory and get a fresh copy of the source:
rm -rf numpy git checkout HEAD .
Then rebuild NumPy by running the
pip install -e . step.
To view the HTML in your browser, the equivalent of the docs top level – that is, of
So for instance your revision of
will be at