aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Documentation/conf.py2
-rw-r--r--Documentation/sphinx-static/custom.css53
-rw-r--r--Documentation/sphinx/templates/translations.html15
-rw-r--r--Documentation/sphinx/translations.py101
4 files changed, 170 insertions, 1 deletions
diff --git a/Documentation/conf.py b/Documentation/conf.py
index a3d1fe9dfcf9..5830b01c5642 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -55,7 +55,7 @@ needs_sphinx = '2.4.4'
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
'maintainers_include', 'sphinx.ext.autosectionlabel',
- 'kernel_abi', 'kernel_feat']
+ 'kernel_abi', 'kernel_feat', 'translations']
if major >= 3:
if (major > 3) or (minor > 0 or patch >= 2):
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index a88ef12428fa..f4285417c71a 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -83,3 +83,56 @@ input.kernel-toc-toggle { display: none; }
h3.kernel-toc-contents { display: inline; }
div.kerneltoc a { color: black; }
}
+
+/* Language selection menu */
+
+div.admonition {
+ /*
+ * Make sure we don't overlap notes and warnings at the top of the
+ * document.
+ */
+ clear: both;
+}
+
+div.language-selection {
+ background: #eeeeee;
+ border: 1px solid #cccccc;
+ margin-bottom: 1em;
+ padding: .5em;
+
+ position: relative;
+ float: right;
+}
+
+div.language-selection a {
+ display: block;
+ padding: 0.5em;
+ color: #333333;
+ text-decoration: none;
+}
+
+div.language-selection ul {
+ display: none;
+ position: absolute;
+
+ /* Align with the parent div */
+ top: 100%;
+ right: 0;
+ margin: 0;
+
+ list-style: none;
+
+ background: #fafafa;
+ border: 1px solid #cccccc;
+
+ /* Never break menu item lines */
+ white-space: nowrap;
+}
+
+div.language-selection:hover ul {
+ display: block;
+}
+
+div.language-selection ul li:hover {
+ background: #dddddd;
+}
diff --git a/Documentation/sphinx/templates/translations.html b/Documentation/sphinx/templates/translations.html
new file mode 100644
index 000000000000..8df5d42d8dcd
--- /dev/null
+++ b/Documentation/sphinx/templates/translations.html
@@ -0,0 +1,15 @@
+<!-- SPDX-License-Identifier: GPL-2.0 -->
+<!-- Copyright © 2023, Oracle and/or its affiliates. -->
+
+{# Create a language menu for translations #}
+{% if languages|length > 0: %}
+<div class="language-selection">
+{{ current_language }}
+
+<ul>
+{% for ref in languages: %}
+<li><a href="{{ ref.refuri }}">{{ ref.astext() }}</a></li>
+{% endfor %}
+</ul>
+</div>
+{% endif %}
diff --git a/Documentation/sphinx/translations.py b/Documentation/sphinx/translations.py
new file mode 100644
index 000000000000..47161e6eba99
--- /dev/null
+++ b/Documentation/sphinx/translations.py
@@ -0,0 +1,101 @@
+# 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):
+ def __init__(self, current_language, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+
+ self.current_language = current_language
+
+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:])
+
+ new_nodes = LanguagesNode(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={
+ '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,
+ }