From cf1d4e6a947daacc125b6acbb3808ef2764b114b Mon Sep 17 00:00:00 2001 From: Rodrigo Tobar Date: Sun, 10 Nov 2024 12:15:46 +0800 Subject: [PATCH 1/4] Split build target into smaller, reusable ones Doing so means we now can reuse the logic that fixes the include:: directives in the cpython documentation in our CI job, avoiding repeating ourselves, making maintenance easier and avoiding subtle bugs. Being able to reuse the rest of the steps (do_build, pospell, etc) requires more care, as the Makefile is constrained to requiring a virtual environment (which we don't create on CI), and also doesn't allow us to pass command-line arguments to list specific files to check. Signed-off-by: Rodrigo Tobar --- .github/workflows/main.yml | 9 +-------- Makefile | 17 +++++++++++------ 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 0df4447290..94b71426f9 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -88,13 +88,6 @@ jobs: # Construcción de la documentación - name: Construir documentación run: | - # FIXME: Relative paths for includes in 'cpython' - sed -i -e 's|.. include:: ../includes/wasm-notavail.rst|.. include:: ../../../../includes/wasm-notavail.rst|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: ../distutils/_setuptools_disclaimer.rst|.. include:: ../../../../distutils/_setuptools_disclaimer.rst|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: ./_setuptools_disclaimer.rst|.. include:: ../../../_setuptools_disclaimer.rst|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: token-list.inc|.. include:: ../../../token-list.inc|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: ../../using/venv-create.inc|.. include:: ../using/venv-create.inc|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: ../../../using/venv-create.inc|.. include:: ../../using/venv-create.inc|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: /using/venv-create.inc|.. include:: ../../../../using/venv-create.inc|g' cpython/Doc/**/*.rst + make fix_relative_paths # Normal build PYTHONWARNINGS=ignore::FutureWarning,ignore::RuntimeWarning sphinx-build -j auto -W --keep-going -b html -d cpython/Doc/_build/doctree -D language=es . cpython/Doc/_build/html diff --git a/Makefile b/Makefile index 8c8268c20b..2eb290b694 100644 --- a/Makefile +++ b/Makefile @@ -38,7 +38,17 @@ help: # before this. If passing SPHINXERRORHANDLING='', warnings will not be # treated as errors, which is good to skip simple Sphinx syntax mistakes. .PHONY: build -build: setup +build: setup fix_relative_paths do_build + +.PHONY: do_build +do_build: + # Normal build + PYTHONWARNINGS=ignore::FutureWarning,ignore::RuntimeWarning $(VENV)/bin/sphinx-build -j auto -W --keep-going -b html -d $(OUTPUT_DOCTREE) -D language=$(LANGUAGE) . $(OUTPUT_HTML) && \ + echo "Success! Open file://`pwd`/$(OUTPUT_HTML)/index.html, " \ + "or run 'make serve' to see them in http://localhost:8000"; + +.PHONY: fix_relative_paths +fix_relative_paths: # FIXME: Relative paths for includes in 'cpython' # See more about this at https://github.com/python/python-docs-es/issues/1844 sed -i -e 's|.. include:: ../includes/wasm-notavail.rst|.. include:: ../../../../includes/wasm-notavail.rst|g' cpython/Doc/**/*.rst @@ -48,11 +58,6 @@ build: setup sed -i -e 's|.. include:: ../../using/venv-create.inc|.. include:: ../using/venv-create.inc|g' cpython/Doc/**/*.rst sed -i -e 's|.. include:: ../../../using/venv-create.inc|.. include:: ../../using/venv-create.inc|g' cpython/Doc/**/*.rst sed -i -e 's|.. include:: /using/venv-create.inc|.. include:: ../../../../using/venv-create.inc|g' cpython/Doc/**/*.rst - # Normal build - PYTHONWARNINGS=ignore::FutureWarning,ignore::RuntimeWarning $(VENV)/bin/sphinx-build -j auto -W --keep-going -b html -d $(OUTPUT_DOCTREE) -D language=$(LANGUAGE) . $(OUTPUT_HTML) && \ - echo "Success! Open file://`pwd`/$(OUTPUT_HTML)/index.html, " \ - "or run 'make serve' to see them in http://localhost:8000"; - # setup: After running "venv" target, prepare that virtual environment with # a local clone of cpython repository and the translation files. From 1d66203612069059ad49269eccf0908642c67ecd Mon Sep 17 00:00:00 2001 From: Rodrigo Tobar Date: Thu, 14 Nov 2024 00:43:08 +0800 Subject: [PATCH 2/4] Shrink and simplify relative path fix list Some of these replacements didn't exist anymore, while others seemed like accidental duplicates that might or might not have been needed to begin with. Signed-off-by: Rodrigo Tobar --- Makefile | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 2eb290b694..9a309a53c3 100644 --- a/Makefile +++ b/Makefile @@ -52,12 +52,8 @@ fix_relative_paths: # FIXME: Relative paths for includes in 'cpython' # See more about this at https://github.com/python/python-docs-es/issues/1844 sed -i -e 's|.. include:: ../includes/wasm-notavail.rst|.. include:: ../../../../includes/wasm-notavail.rst|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: ../distutils/_setuptools_disclaimer.rst|.. include:: ../../../../distutils/_setuptools_disclaimer.rst|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: ./_setuptools_disclaimer.rst|.. include:: ../../../_setuptools_disclaimer.rst|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: token-list.inc|.. include:: ../../../token-list.inc|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: ../../using/venv-create.inc|.. include:: ../using/venv-create.inc|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: ../../../using/venv-create.inc|.. include:: ../../using/venv-create.inc|g' cpython/Doc/**/*.rst - sed -i -e 's|.. include:: /using/venv-create.inc|.. include:: ../../../../using/venv-create.inc|g' cpython/Doc/**/*.rst + sed -i -e 's|.. include:: token-list.inc|.. include:: ../../../token-list.inc|g' cpython/Doc/library/token.rst + sed -i -e 's|.. include:: /using/venv-create.inc|.. include:: ../../../../using/venv-create.inc|g' cpython/Doc/library/venv.rst # setup: After running "venv" target, prepare that virtual environment with # a local clone of cpython repository and the translation files. From c43a44d2e6ef379827f923e64385f3166910b2a7 Mon Sep 17 00:00:00 2001 From: Rodrigo Tobar Date: Sun, 10 Nov 2024 12:20:23 +0800 Subject: [PATCH 3/4] Allow overriding number of sphinx jobs to use Signed-off-by: Rodrigo Tobar --- Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 9a309a53c3..bd24ad4d29 100644 --- a/Makefile +++ b/Makefile @@ -20,6 +20,7 @@ OUTPUT_DOCTREE := $(CPYTHON_WORKDIR)/Doc/build/doctree OUTPUT_HTML := $(CPYTHON_WORKDIR)/Doc/build/html LOCALE_DIR := $(CPYTHON_WORKDIR)/locale POSPELL_TMP_DIR := .pospell +SPHINX_JOBS := auto .PHONY: help @@ -43,7 +44,7 @@ build: setup fix_relative_paths do_build .PHONY: do_build do_build: # Normal build - PYTHONWARNINGS=ignore::FutureWarning,ignore::RuntimeWarning $(VENV)/bin/sphinx-build -j auto -W --keep-going -b html -d $(OUTPUT_DOCTREE) -D language=$(LANGUAGE) . $(OUTPUT_HTML) && \ + PYTHONWARNINGS=ignore::FutureWarning,ignore::RuntimeWarning $(VENV)/bin/sphinx-build -j $(SPHINX_JOBS) -W --keep-going -b html -d $(OUTPUT_DOCTREE) -D language=$(LANGUAGE) . $(OUTPUT_HTML) && \ echo "Success! Open file://`pwd`/$(OUTPUT_HTML)/index.html, " \ "or run 'make serve' to see them in http://localhost:8000"; From 202bfe60c5eef900e129cf570ba3c41d7ad49c24 Mon Sep 17 00:00:00 2001 From: Rodrigo Tobar Date: Tue, 12 Nov 2024 12:25:22 +0800 Subject: [PATCH 4/4] Prefer sphinx-intl 2.3.0 This version performs .po file updates in parallel, thus speeding up the process of moving to new versions of Python and updating our translation files. Signed-off-by: Rodrigo Tobar --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 2fcc7884a6..52096aabef 100644 --- a/requirements.txt +++ b/requirements.txt @@ -10,7 +10,7 @@ potodo powrap python-docs-theme>=2022.1 setuptools -sphinx-intl +sphinx-intl>=2.3.0 pre-commit sphinx-autorun sphinxemoji