Re: [PATCH] docs: translations: add translations links when they exist

[Vegard Nossum]

On 01/11/2023 15:56, Akira Yokosawa wrote:
> It looks like this introduces hysteresis in successive runs of
> "make htmldocs" and "make latexdocs".
>
> Steps to reproduce
>
>    1. Run "make cleandocs"
>
>    2. Run "make htmldocs"
>
>    3. Run "make latexdocs"
>
> This aborts with the message (under Sphinx 7.2.6):
>
>    Extension error (translations):
>    Handler <function process_languages at 0x7f122f343420> for event 'doctree-resolved' threw an exception (exception: 'LaTeXBuilder' object has no attribute 'templates')
>    make[2]: *** [Documentation/Makefile:128: latexdocs] Error 2
>    make[1]: *** [/linux/Makefile:1695: latexdocs] Error 2
>    make: *** [Makefile:234: __sub-make] Error 2
>    Command exited with non-zero status 2
>
> If I run "make latexdocs" in step 2 and "make htmldocs" in step 3,
> both runs complete successfully, but html pages don't have the
> expected links to other translations.
>
> All I can do is to report the symptoms.
> Vegard, can you look into them?

Thanks for testing this out and reporting!

I think we can fix this by moving the "is this html output?" check from
the TranslationsTransform into the 'doctree-resolved' handler (which, as
far as I can tell, runs after the doctree has been serialized to disk
but before output is generated).

I've attached an incremental patch, does that seem to work for you? I
test both (clean/html/latex + clean/latex/html) and it seemed to work here.

I had a look at using a custom "visit" callback that would just render
the HTML in place instead of manipulating the doctree, but it also
doesn't feel right as then you need to specify callbacks for every
output writer; there doesn't seem to be a way to ignore the node by
default. Maybe I should ask on the Sphinx/docutils mailing lists what
the "proper" way to do this would be.

Thanks again!


Vegarddiff --git a/Documentation/sphinx/translations.py b/Documentation/sphinx/translations.py
index 5f2866a12533..99a73075697a 100644
--- a/Documentation/sphinx/translations.py
+++ b/Documentation/sphinx/translations.py
@@ -36,9 +36,6 @@ class TranslationsTransform(Transform):
 
     def apply(self):
         app = self.document.settings.env.app
-        if app.builder.format not in ['html']:
-            return
-
         docname = self.document.settings.env.docname
 
         this_lang_code = None
@@ -70,6 +67,10 @@ class TranslationsTransform(Transform):
 
 def process_languages(app, doctree, docname):
     for node in doctree.traverse(LanguagesNode):
+        if app.builder.format not in ['html']:
+            node.parent.remove(node)
+            continue
+
         languages = []
 
         # Iterate over the child nodes; any resolved links will have