python-peps/docs/build.rst

96 lines
2.1 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
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 linkcheck
``build.py`` usage
------------------
For details on the command-line options to the ``build.py`` script, run:
.. code-block:: shell
python build.py --help