122 lines
2.7 KiB
ReStructuredText
122 lines
2.7 KiB
ReStructuredText
..
|
|
Author: Adam Turner
|
|
|
|
|
|
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 <https://github.com/python/peps>`__, with
|
|
**Python 3.9 or later** installed.
|
|
|
|
|
|
Render PEPs locally
|
|
-------------------
|
|
|
|
1. Create a virtual environment and install requirements:
|
|
|
|
.. code-block:: shell
|
|
|
|
make venv
|
|
|
|
If you don't have access to ``make``, run:
|
|
|
|
.. code-block:: ps1con
|
|
|
|
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.
|
|
|
|
.. code-block:: shell
|
|
|
|
rm -rf build
|
|
|
|
3. Run the build script:
|
|
|
|
.. code-block:: shell
|
|
|
|
make html
|
|
|
|
If you don't have access to ``make``, run:
|
|
|
|
.. code-block:: ps1con
|
|
|
|
(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:
|
|
|
|
.. code-block:: shell
|
|
|
|
source .venv/bin/activate
|
|
|
|
Or on Windows:
|
|
|
|
.. code-block:: ps1con
|
|
|
|
PS> .\.venv\Scripts\activate
|
|
|
|
|
|
Check links
|
|
'''''''''''
|
|
|
|
Check the validity of links within PEP sources (runs the `Sphinx linkchecker
|
|
<https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder>`__).
|
|
|
|
.. code-block:: shell
|
|
|
|
python build.py --check-links
|
|
make check-links
|
|
|
|
|
|
Stricter rendering
|
|
''''''''''''''''''
|
|
|
|
Run in `nit-picky <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky>`__
|
|
mode.
|
|
This generates warnings for all missing references.
|
|
|
|
.. code-block:: shell
|
|
|
|
python build.py --nitpicky
|
|
|
|
Fail the build on any warning.
|
|
As of January 2022, there are around 250 warnings when building the PEPs.
|
|
|
|
.. code-block:: shell
|
|
|
|
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:
|
|
|
|
.. code-block:: shell
|
|
|
|
python build.py --help
|