From cb9d9d3306e6fb3992c58afd6303f0fa7029d2cc Mon Sep 17 00:00:00 2001 From: David Foster Date: Wed, 30 Mar 2022 06:25:32 -0700 Subject: [PATCH 1/4] Build Instructions: Fix to work with the latest Makefile --- docs/build.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/build.rst b/docs/build.rst index 86756a71c5a..4109e30cd9b 100644 --- a/docs/build.rst +++ b/docs/build.rst @@ -17,18 +17,20 @@ installed. Render PEPs locally ------------------- -1. Create a virtual environment and install requirements. - - The rest of these instructions assume an active virtual environment named - ``venv``. - The Python Packaging User Guide contains - `instructions on creating a virtual environment `__ - for reference. +1. Create a virtual environment and install requirements: .. code-block:: console - (venv) $ python -m pip install --upgrade pip - (venv) $ python -m pip install -r requirements.txt + $ 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. @@ -41,7 +43,7 @@ Render PEPs locally .. code-block:: console - (venv) $ make render + $ make render If you don't have access to ``make``, run: From 9d13efd8dc53498a38bd5f7e05419a0b8d9b5792 Mon Sep 17 00:00:00 2001 From: David Foster Date: Wed, 30 Mar 2022 06:30:04 -0700 Subject: [PATCH 2/4] Build Instructions: Emphasize that Python 3.9 or later is required --- docs/build.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build.rst b/docs/build.rst index 4109e30cd9b..29632142b38 100644 --- a/docs/build.rst +++ b/docs/build.rst @@ -10,8 +10,8 @@ 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 `__, with Python 3.9 or later -installed. +`PEPs repository `__, with +**Python 3.9 or later** installed. Render PEPs locally From 13cedbdd708a771949e22926f1633a29a6edf792 Mon Sep 17 00:00:00 2001 From: David Foster Date: Wed, 30 Mar 2022 06:58:24 -0700 Subject: [PATCH 3/4] Build Instructions: Prefer shell code-blocks over console ones ...when dealing with code that can run outside of a venv safely. --- docs/build.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/build.rst b/docs/build.rst index 29632142b38..491fad49a00 100644 --- a/docs/build.rst +++ b/docs/build.rst @@ -19,9 +19,9 @@ Render PEPs locally 1. Create a virtual environment and install requirements: - .. code-block:: console + .. code-block:: shell - $ make venv + make venv If you don't have access to ``make``, run: @@ -35,15 +35,15 @@ Render PEPs locally 2. **(Optional)** Delete prior build files. Generally only needed when making changes to the rendering system itself. - .. code-block:: console + .. code-block:: shell - $ rm -rf build + rm -rf build 3. Run the build script: - .. code-block:: console + .. code-block:: shell - $ make render + make render If you don't have access to ``make``, run: From 5dbea7e0ebd500232be0eed88e37136be1dfcf73 Mon Sep 17 00:00:00 2001 From: David Foster Date: Fri, 15 Apr 2022 08:39:34 -0500 Subject: [PATCH 4/4] Build Instructions: Prefer shell code-blocks over console ones (Part 2) ...for all remaining blocks, including those that use build.py --- docs/build.rst | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/docs/build.rst b/docs/build.rst index 491fad49a00..cb66230e27c 100644 --- a/docs/build.rst +++ b/docs/build.rst @@ -65,6 +65,19 @@ Render PEPs locally 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 ''''''''''' @@ -72,10 +85,10 @@ Check links Check the validity of links within PEP sources (runs the `Sphinx linkchecker `__). -.. code-block:: console +.. code-block:: shell - (venv) $ python build.py --check-links - (venv) $ make check-links + python build.py --check-links + make check-links Stricter rendering @@ -85,17 +98,17 @@ Run in `nit-picky