1
linux/Documentation/sphinx/translations.py

100 lines
2.8 KiB
Python
Raw Permalink Normal View History

# SPDX-License-Identifier: GPL-2.0
#
# Copyright © 2023, Oracle and/or its affiliates.
# Author: Vegard Nossum <vegard.nossum@oracle.com>
#
# Add translation links to the top of the document.
#
import os
from docutils import nodes
from docutils.transforms import Transform
import sphinx
from sphinx import addnodes
from sphinx.errors import NoUri
all_languages = {
# English is always first
None: 'English',
# Keep the rest sorted alphabetically
'zh_CN': 'Chinese (Simplified)',
'zh_TW': 'Chinese (Traditional)',
'it_IT': 'Italian',
'ja_JP': 'Japanese',
'ko_KR': 'Korean',
'sp_SP': 'Spanish',
}
class LanguagesNode(nodes.Element):
docs: translations: use attribute to store current language Akira Yokosawa reported [1] that the "translations" extension we added in commit 7418ec5b151f ("docs: translations: add translations links when they exist") broke the build on Sphinx versions v6.1.3 through 7.1.2 (possibly others) with the following error: Exception occurred: File "/usr/lib/python3.12/site-packages/sphinx/util/nodes.py", line 624, in _copy_except__document newnode = self.__class__(rawsource=self.rawsource, **self.attributes) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ TypeError: LanguagesNode.__init__() missing 1 required positional argument: 'current_language' The full traceback has been saved in /tmp/sphinx-err-7xmwytuu.log, if you want to report the issue to the developers. Solve this problem by making 'current_language' a true element attribute of the LanguagesNode element, which is probably the more correct way to do it anyway. Tested on Sphinx 2.x, 3.x, 6.x, and 7.x. [1]: https://lore.kernel.org/all/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/ Fixes: 7418ec5b151f ("docs: translations: add translations links when they exist") Reported-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Closes: https://lore.kernel.org/all/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/ Tested-by: Akira Yokosawa <akiyks@gmail.com> # Sphinx 4.3.2, 5.3.0 and 6.2.1 Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240215064109.1193556-1-vegard.nossum@oracle.com
2024-02-14 23:41:09 -07:00
pass
class TranslationsTransform(Transform):
default_priority = 900
def apply(self):
app = self.document.settings.env.app
docname = self.document.settings.env.docname
this_lang_code = None
components = docname.split(os.sep)
if components[0] == 'translations' and len(components) > 2:
this_lang_code = components[1]
# normalize docname to be the untranslated one
docname = os.path.join(*components[2:])
docs: translations: use attribute to store current language Akira Yokosawa reported [1] that the "translations" extension we added in commit 7418ec5b151f ("docs: translations: add translations links when they exist") broke the build on Sphinx versions v6.1.3 through 7.1.2 (possibly others) with the following error: Exception occurred: File "/usr/lib/python3.12/site-packages/sphinx/util/nodes.py", line 624, in _copy_except__document newnode = self.__class__(rawsource=self.rawsource, **self.attributes) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ TypeError: LanguagesNode.__init__() missing 1 required positional argument: 'current_language' The full traceback has been saved in /tmp/sphinx-err-7xmwytuu.log, if you want to report the issue to the developers. Solve this problem by making 'current_language' a true element attribute of the LanguagesNode element, which is probably the more correct way to do it anyway. Tested on Sphinx 2.x, 3.x, 6.x, and 7.x. [1]: https://lore.kernel.org/all/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/ Fixes: 7418ec5b151f ("docs: translations: add translations links when they exist") Reported-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Closes: https://lore.kernel.org/all/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/ Tested-by: Akira Yokosawa <akiyks@gmail.com> # Sphinx 4.3.2, 5.3.0 and 6.2.1 Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240215064109.1193556-1-vegard.nossum@oracle.com
2024-02-14 23:41:09 -07:00
new_nodes = LanguagesNode()
new_nodes['current_language'] = all_languages[this_lang_code]
for lang_code, lang_name in all_languages.items():
if lang_code == this_lang_code:
continue
if lang_code is None:
target_name = docname
else:
target_name = os.path.join('translations', lang_code, docname)
pxref = addnodes.pending_xref('', refdomain='std',
reftype='doc', reftarget='/' + target_name, modname=None,
classname=None, refexplicit=True)
pxref += nodes.Text(lang_name)
new_nodes += pxref
self.document.insert(0, new_nodes)
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
# the type 'nodes.reference', while unresolved links will be
# type 'nodes.Text'.
languages = list(filter(lambda xref:
isinstance(xref, nodes.reference), node.children))
html_content = app.builder.templates.render('translations.html',
context={
docs: translations: use attribute to store current language Akira Yokosawa reported [1] that the "translations" extension we added in commit 7418ec5b151f ("docs: translations: add translations links when they exist") broke the build on Sphinx versions v6.1.3 through 7.1.2 (possibly others) with the following error: Exception occurred: File "/usr/lib/python3.12/site-packages/sphinx/util/nodes.py", line 624, in _copy_except__document newnode = self.__class__(rawsource=self.rawsource, **self.attributes) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ TypeError: LanguagesNode.__init__() missing 1 required positional argument: 'current_language' The full traceback has been saved in /tmp/sphinx-err-7xmwytuu.log, if you want to report the issue to the developers. Solve this problem by making 'current_language' a true element attribute of the LanguagesNode element, which is probably the more correct way to do it anyway. Tested on Sphinx 2.x, 3.x, 6.x, and 7.x. [1]: https://lore.kernel.org/all/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/ Fixes: 7418ec5b151f ("docs: translations: add translations links when they exist") Reported-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Closes: https://lore.kernel.org/all/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/ Tested-by: Akira Yokosawa <akiyks@gmail.com> # Sphinx 4.3.2, 5.3.0 and 6.2.1 Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240215064109.1193556-1-vegard.nossum@oracle.com
2024-02-14 23:41:09 -07:00
'current_language': node['current_language'],
'languages': languages,
})
node.replace_self(nodes.raw('', html_content, format='html'))
def setup(app):
app.add_node(LanguagesNode)
app.add_transform(TranslationsTransform)
app.connect('doctree-resolved', process_languages)
return {
'parallel_read_safe': True,
'parallel_write_safe': True,
}