Pequeñas mejoras al proceso de construcción (#2874)

Éstos son pequeños cambios que mejoran ligeramente el proceso de la
construcción de la documentación, y hacen más mantenible el código a
futuro.

Primero, la lista de rutas relativas que hay que arreglar en los .rst de
cpython ha sido simplificada, removiendo entradas innecesarias, y
actualizando sólo los archivos que haga falta (en vez de ejecturas cada
actualización sobre todos los archivos cada vez).

Segundo, el target `build` del Makefile fue separado en sus sub-partes
constituyentes, de tal modo que ahora en el step de CI donde antes
teníamos una copia de los comandos `sed` ahora hay sólo una invocación a
`make fix_relative_paths`.

Finalmente, el PR que envié a `sphinx-intl` para realizar updates en
paralelo [ya está
aceptado](sphinx-doc/sphinx-intl#110) y una
nueva versión ya fue publicada, por lo que la lista de requisitos ahora
está actualizada para usar esa última versión (y así hacer más rápido el
proceso de actualización a 3.13).

---------

Signed-off-by: Rodrigo Tobar <rtobar@icrar.org>

Author: rtobar

.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

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
@@ -38,21 +39,22 @@ 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
-	# 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
+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";
 
+.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
+	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.

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