From 6191d4507da18a36ac8d4cdd0441366e23cf3c29 Mon Sep 17 00:00:00 2001 From: Rodrigo Tobar Date: Mon, 18 Nov 2024 12:49:35 +0800 Subject: [PATCH 1/2] Remove include:: replacements hack We currently need to replace the include:: directives in the cpython documentation source files to fix an issue that sphinx/docutils have with relative source files after changing the app.srcdir in our conf.py. Instead of doing this, let's define the app.srcdir property as an absolute path. This removes the issue altogether, yielding a correct build without the need to modify the documentation source files. This change seems to have the nice side effect that successive builds are not incremental rather than starting from scratch. Signed-off-by: Rodrigo Tobar --- .github/workflows/main.yml | 1 - Makefile | 10 +--------- conf.py | 2 +- 3 files changed, 2 insertions(+), 11 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 94b71426f9..2572e299e0 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -88,6 +88,5 @@ jobs: # Construcción de la documentación - name: Construir documentación run: | - 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 bd24ad4d29..581a2c196c 100644 --- a/Makefile +++ b/Makefile @@ -39,7 +39,7 @@ 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 fix_relative_paths do_build +build: setup do_build .PHONY: do_build do_build: @@ -48,14 +48,6 @@ do_build: 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. # If the directories exists, only update the cpython repository and diff --git a/conf.py b/conf.py index 6d5a7fdb0a..82e5302d07 100644 --- a/conf.py +++ b/conf.py @@ -129,7 +129,7 @@ def add_contributing_banner(app, doctree): document.insert(0, banner) # Change the sourcedir programmatically because Read the Docs always call it with `.` - app.srcdir = 'cpython/Doc' + app.srcdir = os.getcwd() + '/cpython/Doc' app.connect('doctree-read', add_contributing_banner) From 5b571c64cd3fdad302ec7381010d7f84186b6f41 Mon Sep 17 00:00:00 2001 From: Rodrigo Tobar Date: Mon, 18 Nov 2024 14:11:48 +0800 Subject: [PATCH 2/2] Define srcdir as a Path This doesn't break anything, and seems to be required at least in Sphinx 8.1.3, most probably some earlier versions too (we're in 7.2.6). Signed-off-by: Rodrigo Tobar --- conf.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/conf.py b/conf.py index 82e5302d07..f1749d3b19 100644 --- a/conf.py +++ b/conf.py @@ -16,6 +16,8 @@ import sys import os import time +from pathlib import Path + sys.path.append(os.path.abspath('cpython/Doc/tools/extensions')) sys.path.append(os.path.abspath('cpython/Doc/includes')) @@ -70,7 +72,6 @@ if os.environ.get('SPHINX_GETTEXT') is None: # Override all the files from ``.overrides`` directory - from pathlib import Path overrides_paths = Path('.overrides') for path in overrides_paths.glob('**/*.*'): @@ -129,7 +130,7 @@ def add_contributing_banner(app, doctree): document.insert(0, banner) # Change the sourcedir programmatically because Read the Docs always call it with `.` - app.srcdir = os.getcwd() + '/cpython/Doc' + app.srcdir = Path(os.getcwd() + '/cpython/Doc') app.connect('doctree-read', add_contributing_banner)