`sed` en Makefile y GitHub Action

[humitos]

Durante la actualización a 3.11 tuvimos problemas con unos .. include:: de Sphinx que usan path relativos para incluir archivos. No supimos como solucionarlo correctamente y lo que hicimos fue agrear unos sed para actualizar los paths correctamente.

Esta solución no es limpia, pero no tuvimos una mejor forma de resolverlo durante el streaming. Hay que encontrar una solución mejor y actualizar .github/workflows/main.yml y Makefile con la nueva solución.

[humitos]

Pensamos que podríamos utilizar esta instrucción para resolver esto, pero no sabemos que vaya a funcionar: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-include_patterns

También hablamos de buscar una forma de modificar la directiva include para que busque en otros paths también.

[humitos]

La directiva .. include:: usa path relativos al archivo donde se encuentra la directiva. Por lo tanto, me parece bastante raro que no encuentre el archivo y necesitemos usar un sed.

The directive argument is the path to the file to be included, relative to the document containing the directive

(de https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment)

Esto me hizo un poco de ruido hoy...

[humitos]

I think this is a bug in docutils (or how Sphinx passes the source file 🤷🏼 ) at this line https://github.com/jwilk-mirrors/docutils/blob/c4c8ed9cc933a7ccb56c38c56871f7566367952a/docutils/parsers/rst/directives/misc.py#L62

(Pdb) path
'cpython/Doc/library/cpython/Doc/using/venv-create.inc'
(Pdb) print(source)
cpython/Doc/library/venv.rst
(Pdb) print(source_dir)
/home/humitos/Source/python-docs-es/cpython/Doc/library
(Pdb)

It seems it's not able to handle relative paths when changing the app.srcdir in Sphinx (we change this in the conf.py)

[humitos]

Applying this patch I was able to make the build to work without using sed at all:

▶ diff -u misc.py misc.modified.py
--- misc.py	2022-10-29 11:56:49.081491920 +0200
+++ misc.modified.py	2022-10-29 11:56:28.425004994 +0200
@@ -64,6 +64,13 @@
         path = os.path.normpath(os.path.join(source_dir, path))
         path = utils.relative_path(None, path)
         path = nodes.reprunicode(path)
+
+        # Fix these ".. include::" directives in the worst way
+        # NOTE: "cpython/Doc" is the "app.srcdir" and it's duplicated in the resulting ``path``
+        # TODO: see https://github.com/python/python-docs-es/issues/1844
+        # 'cpython/Doc/library/cpython/Doc/using/venv-create.inc'
+        path = 'cpython/Doc/' + path.split('cpython/Doc/')[-1]
+
         encoding = self.options.get(
             'encoding', self.state.document.settings.input_encoding)
         e_handler=self.state.document.settings.input_encoding_error_handler

Now, I'm not 100% who is responsible from this problem. Is it how Sphinx passes the app.srcdir or is Docutils itself? Is it us somehow?

[humitos]

I'd say: "Now that the problem is documented and we barely know why this is happening, I'm fine keeping these not-so-good sed in our build system. I'm sure they will explode in our face in the future, but that's a problem for the future 😄 "

We could try to research a little more about this and try to figure it out if it's a problem in Sphinx and/or Docutils so we can report it to them. The next steps here would be to create a small example project that changes the app.srcdir on the fly and uses .. include:: to try to reproduce it. If we can do that, we will know where to report this bug.

However, _this does not affect python-docs-es at all. So, we can decide to not keep researching about this and focus in moving forward since this only affect our own build and does not have any impact in the official build system.

[github-actions]

Este issue lleva un tiempo sin actualizaciones. ¿Estás trabajando todavía?\nSi necesitas ayuda 🆘 no dudes en contactarnos en nuestro grupo de Telegram.