@@ -105,51 +105,44 @@ There is a Sphinx-rendered version of the PEPs at https://python.github.io/peps/
105105(updated on every push to ``main ``).
106106
107107**Warning: ** This version is not, and should not be taken to be, a canonical
108- source for PEPs whilst it remains in preview (` please report any rendering bugs
109- <https://github.com/python/peps/issues/new> `_). The canonical source for PEPs remains
110- https://www.python.org/dev/peps/
108+ source for PEPs whilst it remains in preview (please ` report any rendering bugs
109+ <https://github.com/python/peps/issues/new> `_).
110+ The canonical source for PEPs remains https://www.python.org/dev/peps/
111111
112- Build PEPs with Sphinx locally:
113- -------------------------------
114112
115- 1. Ensure you have Python >=3.9 and Sphinx installed
116- 2. If you have access to `` make ``, follow (i), otherwise (ii)
113+ Build PEPs with Sphinx locally
114+ ------------------------------
117115
118- i. Run ``make sphinx-local ``
119- ii. Run ``python build.py -j 8 --build-files ``. Note that the jobs argument
120- only takes effect on unix (non-mac) systems.
121- 3. Wait for Sphinx to render the PEPs. There may be a series of warnings about
122- unreferenced citations or labels -- whilst these are valid warnings they do
123- not impact the build process.
124- 4. Navigate to the ``build `` directory of your PEPs repo to find the HTML pages.
125- PEP 0 provides a formatted index, and may be a useful reference.
116+ See the `build documentation <./docs/build.rst >`__ for full step by step
117+ instructions on how to install, build and view the rendered PEPs with Sphinx.
126118
127- Arguments to `` build.py ``:
128- --------------------------
119+ In summary, after installing the dependencies (preferably in a virtual
120+ environment) with:
129121
130- Renderers:
122+ .. code-block :: console
123+
124+ python -m pip install -r requirements.txt
125+
126+ You can build the PEPs with sphinx by running, if your system has ``make ``:
127+
128+ .. code-block :: console
129+
130+ make sphinx
131131
132- ``-f `` or ``--build-files ``
133- Renders PEPs to ``pep-XXXX.html `` files
132+ Otherwise, execute the ``build.py `` script directly:
134133
135- ``-d `` or ``--build-dirs ``
136- Renders PEPs to ``index.html `` files within ``pep-XXXX `` directories
134+ .. code-block :: console
137135
138- Options:
136+ python build.py
139137
140- ``-i `` or ``--index-file ``
141- Copies PEP 0 to a base index file
138+ The output HTML can be found under the ``build `` directory.
142139
143- ``-j `` or ``--jobs ``
144- How many parallel jobs to run (if supported). Integer, default 1
145140
146- ``-n `` or `` --nitpicky ``
147- Runs Sphinx in ` nitpicky ` mode
141+ ``build.py `` usage
142+ ------------------
148143
149- ``-w `` or ``--fail-on-warning ``
150- Fails Sphinx on warnings
144+ For details on the command-line options to the ``build.py `` script, run:
151145
152- Tools:
146+ .. code-block :: console
153147
154- ``-l `` or ``--check-links ``
155- Checks validity of links within PEP sources
148+ python build.py --help
0 commit comments