From 9a478e3c22e53b478261230be6c21ecf45c31294 Mon Sep 17 00:00:00 2001 From: Rodrigo Tobar Date: Fri, 22 Nov 2024 14:02:22 +0800 Subject: [PATCH 1/3] Clarify `make build -j` double red herring During the migration to 3.13 it was suggested to use `make build -j` to automatically speed up the building process of the documentation to use all available cores. This is red herring in two different ways: * `make`'s `-j` flag can be used to parallelise the processing of `make` target dependencies instead of magically apply parallelisation to the underlying commands. In our case the `make build` command has a sequential sequence of dependencies (venv -> setup -> do_build) so no actual parallelisation is achieved when passing `-j`. `sphinx-build` can be parallelised by giving *it* a `-j` flag, which we already do (`-j auto`). In other words, there's nothing to do on our side to speed things up even further. What we *do* have though is a `make` `SPHINX_JOBS` variable, which acts as the argument to `sphinx-build -j`. Using this users can reduce the number of CPUs they want to use for the build process. * Secondly, an empty `make -j` option (i.e., without a number afterwards), contrary to popular belief, runs as many recipes in parallel as possible [1], *with no regards to the number of available cores*. In most scenarios this is fine because the number of dependencies for a given target isn't that great, or because the target instructions are not that heavy, but it can generate difficult-to-understand problems on occasion. For example, if you are building a shared library that consists on 250 files of heavy C++, you'll end up spawning 250 C++ compilers at the same time, which surely will consume all the memory of your computer, causing them to be OOM-killed. Bottom-line is: never use -j without a value. Signed-off-by: Rodrigo Tobar --- .overrides/upgrade-python-version.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.overrides/upgrade-python-version.rst b/.overrides/upgrade-python-version.rst index e4505f4409..72c4fa2a23 100644 --- a/.overrides/upgrade-python-version.rst +++ b/.overrides/upgrade-python-version.rst @@ -48,9 +48,11 @@ We are currently in branch 3.12, and we want to update the strings from 3.13. .. note:: - You can also run `make build -j` to use more than 1 core (but keep in mind - this is not always faster). + The underlying ``sphinx-build`` command uses all available cores by default. + Use the ``SPHINX_JOBS`` ``make`` variable (defaults to ``auto``) + to specify an explicit amount, e.g. ``make build SPHINX_JOBS=10``. + .. note:: It may fail the build because there may be files that don't exist anymore in the new branch. If that's the case, just continue with the steps From 526beb47c1b543738c84c1ba379250c4f8aa6a1a Mon Sep 17 00:00:00 2001 From: Rodrigo Tobar Date: Fri, 22 Nov 2024 14:27:28 +0800 Subject: [PATCH 2/3] Use sphinx~=8.0.0 as intended 8.1 introduces the built-in cvw/cwe roles. During the migration the requirement was bumped to 8.1 while trying to sort out a problem with the pypi role, which turned out to be the cpython submodule not being committed/pushed properly earlier, and hence the update wasn't necessary (and broke things). Signed-off-by: Rodrigo Tobar --- conf.py | 9 --------- requirements.txt | 2 +- 2 files changed, 1 insertion(+), 10 deletions(-) diff --git a/conf.py b/conf.py index b7c1b644d3..7024156062 100644 --- a/conf.py +++ b/conf.py @@ -29,15 +29,6 @@ sys.path.insert(0, os.path.abspath('cpython/Doc')) from conf import * -# FIXME -# For fixing the warnings that state that 'cwe', 'cve' roles are already -# defined. -# -# WARNING: role 'cve' is already registered, it will be overridden [app.add_role] -# WARNING: role 'cwe' is already registered, it will be overridden [app.add_role] -del extlinks["cwe"] -del extlinks["cve"] - # Call patchlevel with the proper path to get the version from # instead of hardcoding it from patchlevel import get_version_info diff --git a/requirements.txt b/requirements.txt index a2ea7742eb..234449bb8d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -16,7 +16,7 @@ sphinx-lint==0.7.0 tabulate # from cpython/Doc/requirements.txt -sphinx~=8.1.0 +sphinx~=8.0.0 blurb From e55d799c61f9b22fbb7836ce6df9a8a7c1651c9d Mon Sep 17 00:00:00 2001 From: Rodrigo Tobar Date: Fri, 22 Nov 2024 14:33:24 +0800 Subject: [PATCH 3/3] Remove unnecessary conf.py overrides These are already defined in cpython's, let's thus remove the amount of overriding we need to provide. Signed-off-by: Rodrigo Tobar --- conf.py | 7 ------- 1 file changed, 7 deletions(-) diff --git a/conf.py b/conf.py index 7024156062..0d39ed17d9 100644 --- a/conf.py +++ b/conf.py @@ -29,14 +29,7 @@ sys.path.insert(0, os.path.abspath('cpython/Doc')) from conf import * -# Call patchlevel with the proper path to get the version from -# instead of hardcoding it -from patchlevel import get_version_info -version, release = get_version_info() - project = 'Python en Español' -year = time.strftime("%Y") -copyright = f'2001-{year}, Python Software Foundation' html_theme_path = ['cpython/Doc/tools'] templates_path = ['cpython/Doc/tools/templates'] pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy