Whilst editing a PEP, it is useful to review the rendered output locally. This can also be used to check that the PEP is valid reStructuredText before submission to the PEP editors.
The rest of this document assumes you are working from a local clone of the PEPs repository, with Python 3.9 or later installed.
Install requirements
$ python -m venv venv $ . venv/bin/activate (venv) $ python -m pip install --upgrade pip (venv) $ python -m pip install -r requirements.txt
(Optional) Delete prior build files. Generally only needed when changing the rendering system itself.
$ rm -rf build
Run the build script:
(venv) $ make sphinx
If you don't have access to
make
, run:(venv) PS> python build.py -j 8
Caution!
There may be a series of warnings about unreferenced citations or labels -- whilst these are valid warnings they do not impact the build process.
Navigate to the
build
directory of your PEPs repo to find the HTML pages. PEP 0 provides a formatted index, and may be a useful reference.
Several additional tools can be run through build.py
, or the Makefile.
Check the validity of links within PEP sources (runs the Sphinx linkchecker)
(venv) $ python build.py --check-links
(venv) $ make check-links
Run in nit-picky mode. This generates warnings for all missing references.
(venv) $ python build.py --nitpicky
Fail the build on any warning. As of January 2022 there are around 250 warnings when building the PEPs.
(venv) $ python build.py --fail-on-warning
(venv) $ make fail-warning
Renderers:
-f
or--build-files
- Renders PEPs to
pep-XXXX.html
files (Default) -d
or--build-dirs
- Renders PEPs to
index.html
files withinpep-XXXX
directories
Options:
-i
or--index-file
- Copies PEP 0 to a base index file
-j
or--jobs
- How many parallel jobs to run (if supported). Integer, default 1
-n
or--nitpicky
- Runs Sphinx in nitpicky mode
-w
or--fail-on-warning
- Fails Sphinx on warnings
Tools:
-l
or--check-links
- Checks validity of links within PEP sources