Remove include:: replacements hack (#2875)

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.

Edit: additionally, we now define sphinx's `app.srcdir` as a Path, which
seems to be a requirement at least in 8.1.3, which is what we''l use for
building the 3.13 docs. See
sphinx-doc/sphinx#13018.

Closes #1844

---------

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

Author: rtobar

.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

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

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 = 'cpython/Doc'
+    app.srcdir = Path(os.getcwd() + '/cpython/Doc')
 
     app.connect('doctree-read', add_contributing_banner)