From 96f1ef6331c19ac94f6a19490da741dcbdbb1ef4 Mon Sep 17 00:00:00 2001 From: Nacho Caballero Date: Sat, 19 Jul 2025 15:21:44 +0200 Subject: [PATCH 1/6] prevent `make venv` from falsely reporting success --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index 9817feb15..49815f2f3 100644 --- a/Makefile +++ b/Makefile @@ -57,6 +57,7 @@ venv: .PHONY: ensure-venv ensure-venv: + set -e; @if [ ! -d $(VENVDIR) ] ; then \ echo "Creating venv in $(VENVDIR)"; \ if $(UV) --version >/dev/null 2>&1; then \ From 321eb50c00ccb667dcf8bb64ea9f173632f985f2 Mon Sep 17 00:00:00 2001 From: Nacho Caballero Date: Sat, 19 Jul 2025 15:21:53 +0200 Subject: [PATCH 2/6] improve initial requirement docs --- documentation/start-documenting.rst | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 973b36b12..189dd4964 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -76,12 +76,24 @@ To build the documentation, follow the steps in one of the sections below. You can view the documentation after building the HTML by opening the file :file:`Doc/build/html/index.html` in a web browser. -.. note:: +.. _doc-initial-requirements: + +Initial requirements +-------------------- + + +Ensure your current working dir is the ``Doc`` subdirectory in your +:ref:`CPython repository clone `. + +.. code-block:: shell + + cd Doc + +Ensure your Python version is at least 3.11 (Sphinx requirement). - The following instructions all assume your current working dir is - the ``Doc`` subdirectory in your :ref:`CPython repository clone `. - Make sure to switch to it with ``cd Doc`` if necessary. +.. code-block:: shell + python --version .. _doc-create-venv: From b9352256ebc7e278f01c34c3b151cbe543e0eaf5 Mon Sep 17 00:00:00 2001 From: Nacho Caballero Date: Sat, 19 Jul 2025 15:52:51 +0200 Subject: [PATCH 3/6] fix location of `set -e` --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 49815f2f3..3d485ae2d 100644 --- a/Makefile +++ b/Makefile @@ -57,8 +57,8 @@ venv: .PHONY: ensure-venv ensure-venv: - set -e; @if [ ! -d $(VENVDIR) ] ; then \ + set -e; \ echo "Creating venv in $(VENVDIR)"; \ if $(UV) --version >/dev/null 2>&1; then \ $(UV) venv --python=$(PYTHON) $(VENVDIR); \ From 235c4d1d80ac9bb5d0effa627afade75f1ecb579 Mon Sep 17 00:00:00 2001 From: Nacho Caballero Date: Sat, 19 Jul 2025 16:01:09 +0200 Subject: [PATCH 4/6] Fix docs --- documentation/start-documenting.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 189dd4964..f770131d5 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -76,24 +76,22 @@ To build the documentation, follow the steps in one of the sections below. You can view the documentation after building the HTML by opening the file :file:`Doc/build/html/index.html` in a web browser. -.. _doc-initial-requirements: - Initial requirements -------------------- - -Ensure your current working dir is the ``Doc`` subdirectory in your -:ref:`CPython repository clone `. +Ensure your current working directory is the top level ``Doc/`` directory +inside your :ref:`CPython repository clone `. .. code-block:: shell - cd Doc + cd Doc -Ensure your Python version is at least 3.11 (Sphinx requirement). +Ensure your Python version is at least 3.11. .. code-block:: shell - python --version + $ python --version + Python 3.13.5 .. _doc-create-venv: From 620d9e9bdaccfd7a6947bc7cf3ab92bb9fd7c9f8 Mon Sep 17 00:00:00 2001 From: Nacho Caballero Date: Sat, 19 Jul 2025 16:26:23 +0200 Subject: [PATCH 5/6] make it clear that it's an optional step --- documentation/start-documenting.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index f770131d5..0398eba44 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -80,7 +80,8 @@ Initial requirements -------------------- Ensure your current working directory is the top level ``Doc/`` directory -inside your :ref:`CPython repository clone `. +inside your :ref:`CPython repository clone `. You can switch to +it with: .. code-block:: shell From eed589cf9d1ec934cf59a2ec4d8c4c4daf1fd10c Mon Sep 17 00:00:00 2001 From: Nacho Caballero Date: Sat, 19 Jul 2025 16:29:10 +0200 Subject: [PATCH 6/6] explain that the second step is also optional --- documentation/start-documenting.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 0398eba44..7515992ec 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -87,12 +87,11 @@ it with: cd Doc -Ensure your Python version is at least 3.11. +Ensure your Python version is at least 3.11. You can verify it with: .. code-block:: shell - $ python --version - Python 3.13.5 + python --version .. _doc-create-venv: