[PATCH] docs: Only load the translations extension for HTML output

[PATCH] docs: Only load the translations extension for HTML output

[Jonathan Corbet]

This extension brings no value for other output formats and can create
problems with the pdfdocs build.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 5830b01c5642..6071d3e24375 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -55,7 +55,13 @@ needs_sphinx = '2.4.4'
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat', 'translations']
+              'kernel_abi', 'kernel_feat']
+#
+# Only enable the translation extension if we are building the HTML docs;
+# it brings no value otherwise and can cause problems.
+#
+if 'html' in sys.argv:
+    extensions.append('translations')
 
 if major >= 3:
     if (major > 3) or (minor > 0 or patch >= 2):
-- 
2.43.0

Re: [PATCH] docs: Only load the translations extension for HTML output

[Akira Yokosawa]

Hi Jon,

On 2024/02/15 8:25, Jonathan Corbet wrote:
> This extension brings no value for other output formats and can create
> problems with the pdfdocs build.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/conf.py | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 5830b01c5642..6071d3e24375 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -55,7 +55,13 @@ needs_sphinx = '2.4.4'
>  extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
>                'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
>                'maintainers_include', 'sphinx.ext.autosectionlabel',
> -              'kernel_abi', 'kernel_feat', 'translations']
> +              'kernel_abi', 'kernel_feat']
> +#
> +# Only enable the translation extension if we are building the HTML docs;
> +# it brings no value otherwise and can cause problems.
> +#
> +if 'html' in sys.argv:
> +    extensions.append('translations')

I tested incremental build of latexdocs against Sphinx 7.2.6 as follows:

    make cleandocs
    make htmldocs
    make latexdocs

Without this change, "make latexdocs" completes 2 or 3 minutes
quicker than full builds.

With this change applied and against Sphinx 7.2.6, "make latexdocs"
slows down significantly (the same as the slowdown of incremental
builds reported elsewhere), and it ends up in an exception, whose
message reads:

--------------------------
WARNING: unknown node type: <LanguagesNode: <#text: 'Chinese (Simpl ...'><#text: 'Chinese (Tradi ... ...>

Exception occurred:
  File "/home/akira/sphinx-7.2.6/lib/python3.10/site-packages/docutils/nodes.py", line 2068, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.latex.LaTeXTranslator'> departing unknown node type: LanguagesNode
The full traceback has been saved in /tmp/sphinx-err-3inve171.log, if you want to report the issue to the developers.
--------------------------

I don't see the error against Sphinx 4.3.2 (of Ubuntu 22.04).
So it is (again) dependent on Sphinx or docutils version.

For v6.8, how about loading translations extension with
Sphinx<6.1.3 or Sphinx>=7.2 for all the builders.

Note that Linux distros to be released in a couple of month,
Ubuntu 24.04 and Fedora 40 have Sphinx 7.2.6 in their pre-release
repository.  openSUSE Leap 15.5 already has 7.2.6 as a package
of the name python311-Sphinx.

        Thanks, Akira

>  
>  if major >= 3:
>      if (major > 3) or (minor > 0 or patch >= 2):

Re: [PATCH] docs: Only load the translations extension for HTML output

[Vegard Nossum]

On 15/02/2024 03:43, Akira Yokosawa wrote:
> On 2024/02/15 8:25, Jonathan Corbet wrote:
>> +#
>> +# Only enable the translation extension if we are building the HTML docs;
>> +# it brings no value otherwise and can cause problems.
>> +#
>> +if 'html' in sys.argv:
>> +    extensions.append('translations')
> 
> I tested incremental build of latexdocs against Sphinx 7.2.6 as follows:

[...]

> WARNING: unknown node type: <LanguagesNode: <#text: 'Chinese (Simpl ...'><#text: 'Chinese (Tradi ... ...>
> 
> Exception occurred:
>    File "/home/akira/sphinx-7.2.6/lib/python3.10/site-packages/docutils/nodes.py", line 2068, in unknown_departure
>      raise NotImplementedError(
> NotImplementedError: <class 'sphinx.writers.latex.LaTeXTranslator'> departing unknown node type: LanguagesNode
> The full traceback has been saved in /tmp/sphinx-err-3inve171.log, if you want to report the issue to the developers.

Jon, this is pretty much what I said would happen here:

https://lore.kernel.org/all/8b51b6d6-0360-4f42-9b96-02e0ccd0b34f@oracle.com/

I have a proper fix that should fix all errors everywhere:

https://lore.kernel.org/all/4806c264-1076-401b-bb5f-283fb7b68fb3@oracle.com/

Why not use that? I'll do a proper submission, I was just waiting a
couple of days to see if anybody else would would test it too.


Vegard

Re: [PATCH] docs: Only load the translations extension for HTML output

[Akira Yokosawa]

Hi Vegard,

On 2024/02/15 15:22, Vegard Nossum wrote:
> 
> On 15/02/2024 03:43, Akira Yokosawa wrote:
>> On 2024/02/15 8:25, Jonathan Corbet wrote:
>>> +#
>>> +# Only enable the translation extension if we are building the HTML docs;
>>> +# it brings no value otherwise and can cause problems.
>>> +#
>>> +if 'html' in sys.argv:
>>> +    extensions.append('translations')
>>
>> I tested incremental build of latexdocs against Sphinx 7.2.6 as follows:
> 
> [...]
> 
>> WARNING: unknown node type: <LanguagesNode: <#text: 'Chinese (Simpl ...'><#text: 'Chinese (Tradi ... ...>
>>
>> Exception occurred:
>>    File "/home/akira/sphinx-7.2.6/lib/python3.10/site-packages/docutils/nodes.py", line 2068, in unknown_departure
>>      raise NotImplementedError(
>> NotImplementedError: <class 'sphinx.writers.latex.LaTeXTranslator'> departing unknown node type: LanguagesNode
>> The full traceback has been saved in /tmp/sphinx-err-3inve171.log, if you want to report the issue to the developers.
> 
> Jon, this is pretty much what I said would happen here:
> 
> https://lore.kernel.org/all/8b51b6d6-0360-4f42-9b96-02e0ccd0b34f@oracle.com/
> 
> I have a proper fix that should fix all errors everywhere:
> 
> https://lore.kernel.org/all/4806c264-1076-401b-bb5f-283fb7b68fb3@oracle.com/

Oh, that's even better!

> 
> Why not use that? I'll do a proper submission, I was just waiting a
> couple of days to see if anybody else would would test it too.

I didn't respond because I mistook your words

> I'll test a bit more and submit a proper patch if this works.

and decided to wait for a proper patch from you.  I was thinking
the delay meant there was something you needed to work further...

I've just tested your proper patch and it worked across v4.3.2 (of
Ubuntu 22.04) and V6.2.1 (of Fedora 39), among others.

Many thanks,
Akira

> 
> 
> Vegard

Re: [PATCH] docs: Only load the translations extension for HTML output

[Vegard Nossum]

On 15/02/2024 12:10, Akira Yokosawa wrote:
> On 2024/02/15 15:22, Vegard Nossum wrote:
>> Jon, this is pretty much what I said would happen here:
>>
>> https://lore.kernel.org/all/8b51b6d6-0360-4f42-9b96-02e0ccd0b34f@oracle.com/
>>
>> I have a proper fix that should fix all errors everywhere:
>>
>> https://lore.kernel.org/all/4806c264-1076-401b-bb5f-283fb7b68fb3@oracle.com/
> 
> Oh, that's even better!
> 
>>
>> Why not use that? I'll do a proper submission, I was just waiting a
>> couple of days to see if anybody else would would test it too.
> 
> I didn't respond because I mistook your words

Rereading my email I see that it is ambiguous, sorry for the confusion.

>> I'll test a bit more and submit a proper patch if this works.
> 
> and decided to wait for a proper patch from you.  I was thinking
> the delay meant there was something you needed to work further...
> 
> I've just tested your proper patch and it worked across v4.3.2 (of
> Ubuntu 22.04) and V6.2.1 (of Fedora 39), among others.

Thank you!


Vegard

Re: [PATCH] docs: Only load the translations extension for HTML output

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> I tested incremental build of latexdocs against Sphinx 7.2.6 as follows:
>
>     make cleandocs
>     make htmldocs
>     make latexdocs
>
> Without this change, "make latexdocs" completes 2 or 3 minutes
> quicker than full builds.

> With this change applied and against Sphinx 7.2.6, "make latexdocs"
> slows down significantly (the same as the slowdown of incremental
> builds reported elsewhere), and it ends up in an exception, whose
> message reads:

That, I must confess, mystifies me completely, the slowdown especially.

Oh well, I'll drop this and look at Vegard's patch.

Thanks,

jon