Review Sphinx build problem

[humitos]

I had to remove these two paragraphs, https://github.com/python/python-docs-es/pull/1220/files#diff-76e825af3419a1d9a7d6f11b9073a2f39bfa86a97d9534d275ecb28d9b8c1116L79-L101

because I was receiving

cpython/Doc/library/sys.rst:38:inconsistent term references in translated message. original: [':func:`sys.addaudithook`', ':class:`RuntimeError`'], translated: [':ref:`auditing event <auditing>`']

all the time and that made the build to fail.

We will need to re-add those paragraphs and find out a solution.

References:

• inconsistent term references in translated message when building python doc sphinx-doc/sphinx#8932
• Fixed linenumber missing when audit hook has an error cpython#24692

[humitos]

I'm asking about this on #python-docs on freenode

I think I found something weird at Sphinx level. I put a pdb at this line https://github.com/sphinx-doc/sphinx/blob/72ad5f2a98c60d2b1cd856b6b9057ac5b5c85edd/sphinx/transforms/i18n.py#L402 and this called my attention

(Pdb++) node.rawsource
'Raises an :ref:`auditing event <auditing>` ``sys.addaudithook`` with no arguments.'
(Pdb++) old_xrefs
[<pending_xref: <literal...>>, <pending_xref: <literal...>>]
(Pdb++) old_xrefs[0].rawsource
':func:`sys.addaudithook`'
(Pdb++) old_xrefs[1].rawsource
':class:`RuntimeError`'
(Pdb++) node
<paragraph: <paragraph...>>
(Pdb++) 

Note that the node.rawsource only have one :ref: but the old_xrefs shows 2 references and they are completely different 🤔. On the other hand, patch node (the translated one) shows the correct translated paragraph with the proper xrefs

(Pdb++) patch.rawsource
'Lanza un :ref:`auditing event <auditing>` ``sys.addaudithook`` sin argumentos.'
(Pdb++) new_xrefs[0].rawsource
':ref:`auditing event <auditing>`'

[humitos]

looks like a matching problem: old_xrefs contains the references of the next paragraph in the .po file (from #: ../Doc/library/sys.rst:40 instead of #: ../Doc/library/sys.rst:38). This paragraph is "the content" of the directive .. audit-event::
I found the exact same situation happens in https://github.com/python/cpython/blob/e8e341993e3f80a3c456fb8e0219530c93c13151/Doc/c-api/sys.rst#L363-L370 --However, in this .rst file it works properly. I'm trying to find out what are the differences

yeap, the patched node does not contains the content of the .. audit-event:: directive, but the original does:

[<paragraph: <paragraph...>>, <paragraph: <#text: 'Calling '><pending_xref...><#text: ' will itsel ...>, <#text: 'Calling '>, <pending_xref: <literal...>>, <literal: <#text: 'sys.addaudithook()'>>, <#text: 'sys.addaudithook()'>, <#text: ' will itself raise an auditing event\nnamed '>, <literal: <#text: 'sys.addaudithook'>>, <#text: 'sys.addaudithook'>, <#text: ' with no arguments. If any\nexisting hooks raise an 
exception der ...'>, <pending_xref: <literal...>>, <literal: <#text: 'RuntimeError'>>, <#text: 'RuntimeError'>, <#text: ', the\nnew hook will not be added and the exception suppressed. A ...'>]
(Pdb++) patch.traverse()
[<paragraph: <#text: 'Lanza un '><pending_xref...><#text: ' '><litera ...>, <#text: 'Lanza un '>, <pending_xref: <inline...>>, <inline: <#text: 'auditing event'>>, <#text: 'auditing event'>, <#text: ' '>, <literal: <#text: 'sys.addaudithook'>>, <#text: 'sys.addaudithook'>, <#text: ' sin argumentos.'>]
(Pdb++) 

I'm guessing that i18n Sphinx's translator is doing something weird with this particular node that removes the content of the directive --I'm trying to check that
ha! I found another weird thing. The case for c-api/sys.rst seems broken as well, but it does work because pending refs match by lucky...
seems the catalog.gettext(msg) returns something weird

'Raises an :ref:`auditing event <auditing>` ``sys.addaudithook`` with no arguments.'
(Pdb++) patch.rawsource
'Ver :pep:`578` para una descripción detallada de la auditoría. Las funciones en el tiempo de ejecución y la biblioteca estándar que generan eventos se enumeran en :ref:`table de eventos de auditoria <audit-events>`. Los detalles se encuentran en la documentación de cada función.'
(Pdb++)

[humitos]

Esto no falla más.