From ce06c192c02c2758ac6b235ef309a7c07163e580 Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Wed, 30 Jun 2021 22:46:39 +0100 Subject: [PATCH 1/5] Add build process notes to README.rst --- README.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/README.rst b/README.rst index fe4288ff91f..78b25803e73 100644 --- a/README.rst +++ b/README.rst @@ -70,3 +70,51 @@ rendering pipeline: local clone of the PEP repository * Run ``./manage.py generate_pep_pages`` as described in https://pythondotorg.readthedocs.io/pep_generation.html + + +Rendering PEPs with Sphinx +========================== + +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) + + 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. + +Arguments to the build file: +---------------------------- + +Renderers: + +``-f`` or ``--build-files`` + Renders PEPs to ``pep-XXXX.html`` files + +``-d`` or ``--build-dirs`` + Renders PEPs to ``index.html`` files within ``pep-XXXX`` directories + +Options: + +``-i`` or ``--index-file`` + Copies PEP 0 to a base index file + +``-j`` or ``--jobs`` + How many parallel jobs to run (if supported). Integer, default 1 + +``-n`` or ``--nitpicky`` + Runs Sphinx in `nitpicky` mode + +``-w`` or ``--fail-on-warning`` + Fails Sphinx on warnings + +Tools: + +``-l`` or ``--check-links`` + Checks validity of links within PEP sources From 07e7877526475daf4fc78163caeb46b02cbb1216 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Wed, 30 Jun 2021 22:54:07 +0100 Subject: [PATCH 2/5] Loosen restriction on 3.9 Co-authored-by: Pablo Galindo --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 78b25803e73..2db100a0fbc 100644 --- a/README.rst +++ b/README.rst @@ -78,7 +78,7 @@ Rendering PEPs with Sphinx Build PEPs with Sphinx locally: ------------------------------- -1. Ensure you have Python 3.9 and Sphinx installed +1. Ensure you have Python >=3.9 and Sphinx installed 2. If you have access to ``make``, follow (i), otherwise (ii) i. Run ``make sphinx-local`` From 698cfe525cb60a296dce1b4546fa32f81467401c Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Wed, 30 Jun 2021 22:55:27 +0100 Subject: [PATCH 3/5] Disambiguate build file --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 2db100a0fbc..8aa853e5273 100644 --- a/README.rst +++ b/README.rst @@ -89,8 +89,8 @@ Build PEPs with Sphinx locally: not impact the build process. 4. Navigate to the ``build`` directory of your PEPs repo to find the HTML pages. -Arguments to the build file: ----------------------------- +Arguments to ``build.py``: +-------------------------- Renderers: From f1c27680d1fa8c83b9db1e1a6c3cf38f0fa9332d Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Thu, 1 Jul 2021 00:33:26 +0100 Subject: [PATCH 4/5] Add note about GitHib Pages preview. Closes #2017 --- README.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.rst b/README.rst index 8aa853e5273..ca8d00c938c 100644 --- a/README.rst +++ b/README.rst @@ -75,6 +75,14 @@ rendering pipeline: Rendering PEPs with Sphinx ========================== +There is a Sphinx-rendered version of the PEPs at https://python.github.io/peps/ +(updated on every push to ``master``) + +**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 +`_). The canonical source for PEPs remains +https://www.python.org/dev/peps/ + Build PEPs with Sphinx locally: ------------------------------- From 5b7dce571fcc4e703191da5856de9571b1415928 Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Thu, 1 Jul 2021 00:47:13 +0100 Subject: [PATCH 5/5] Add suggestion to use PEP 0 --- README.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/README.rst b/README.rst index ca8d00c938c..2bd3035636f 100644 --- a/README.rst +++ b/README.rst @@ -96,6 +96,7 @@ Build PEPs with Sphinx locally: 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. Arguments to ``build.py``: --------------------------