Skip to content

Latest commit

 

History

History
121 lines (70 loc) · 2.68 KB

build.rst

File metadata and controls

121 lines (70 loc) · 2.68 KB

Building PEPs Locally

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.

Render PEPs locally

  1. Create a virtual environment and install requirements:

    make venv

    If you don't have access to make, run:

    PS> python -m venv .venv
    PS> .\.venv\Scripts\activate
    (venv) PS> python -m pip install --upgrade pip
    (venv) PS> python -m pip install -r requirements.txt
    
  2. (Optional) Delete prior build files. Generally only needed when making changes to the rendering system itself.

    rm -rf build
  3. Run the build script:

    make html

    If you don't have access to make, run:

    (venv) PS> python build.py
    

    Note

    There may be a series of warnings about unreferenced citations or labels. Whilst these are valid warnings, they do not impact the build process.

  4. 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.

build.py tools

Several additional tools can be run through build.py, or the Makefile.

Note that before using build.py you must activate the virtual environment created earlier:

source .venv/bin/activate

Or on Windows:

PS> .\.venv\Scripts\activate

Check links

Check the validity of links within PEP sources (runs the Sphinx linkchecker).

python build.py --check-links
make check-links

Stricter rendering

Run in nit-picky mode. This generates warnings for all missing references.

python build.py --nitpicky

Fail the build on any warning. As of January 2022, there are around 250 warnings when building the PEPs.

python build.py --fail-on-warning
make fail-warning

build.py usage

For details on the command-line options to the build.py script, run:

python build.py --help