Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 27 additions & 34 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -105,51 +105,44 @@ There is a Sphinx-rendered version of the PEPs at https://python.github.io/peps/
(updated on every push to ``main``).

**Warning:** This version is not, and should not be taken to be, a canonical
source for PEPs whilst it remains in preview (`please report any rendering bugs
<https://github.com/python/peps/issues/new>`_). The canonical source for PEPs remains
https://www.python.org/dev/peps/
source for PEPs whilst it remains in preview (please `report any rendering bugs
<https://github.com/python/peps/issues/new>`_).
The canonical source for PEPs remains https://www.python.org/dev/peps/

Build PEPs with Sphinx locally:
-------------------------------

1. Ensure you have Python >=3.9 and Sphinx installed
2. If you have access to ``make``, follow (i), otherwise (ii)
Build PEPs with Sphinx locally
------------------------------

i. Run ``make sphinx-local``
ii. Run ``python build.py -j 8 --build-files``. Note that the jobs argument
only takes effect on unix (non-mac) systems.
3. Wait for Sphinx to render the PEPs. 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.
See the `build documentation <./docs/build.rst>`__ for full step by step
instructions on how to install, build and view the rendered PEPs with Sphinx.

Arguments to ``build.py``:
--------------------------
In summary, after installing the dependencies (preferably in a virtual
environment) with:

Renderers:
.. code-block:: console

python -m pip install -r requirements.txt

You can build the PEPs with sphinx by running, if your system has ``make``:

.. code-block:: console

make sphinx

``-f`` or ``--build-files``
Renders PEPs to ``pep-XXXX.html`` files
Otherwise, execute the ``build.py`` script directly:

``-d`` or ``--build-dirs``
Renders PEPs to ``index.html`` files within ``pep-XXXX`` directories
.. code-block:: console

Options:
python build.py

``-i`` or ``--index-file``
Copies PEP 0 to a base index file
The output HTML can be found under the ``build`` directory.

``-j`` or ``--jobs``
How many parallel jobs to run (if supported). Integer, default 1

``-n`` or ``--nitpicky``
Runs Sphinx in `nitpicky` mode
``build.py`` usage
------------------

``-w`` or ``--fail-on-warning``
Fails Sphinx on warnings
For details on the command-line options to the ``build.py`` script, run:

Tools:
.. code-block:: console

``-l`` or ``--check-links``
Checks validity of links within PEP sources
python build.py --help