summaryrefslogtreecommitdiffstats
path: root/Documentation/sphinx
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/sphinx')
-rw-r--r--Documentation/sphinx/automarkup.py26
-rw-r--r--Documentation/sphinx/cdomain.py6
-rw-r--r--Documentation/sphinx/kfigure.py8
-rw-r--r--Documentation/sphinx/requirements.txt3
-rw-r--r--Documentation/sphinx/templates/kernel-toc.html4
-rw-r--r--Documentation/sphinx/templates/translations.html15
-rw-r--r--Documentation/sphinx/translations.py99
7 files changed, 142 insertions, 19 deletions
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 06b34740bf..a413f8dd51 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -7,11 +7,7 @@
from docutils import nodes
import sphinx
from sphinx import addnodes
-if sphinx.version_info[0] < 2 or \
- sphinx.version_info[0] == 2 and sphinx.version_info[1] < 1:
- from sphinx.environment import NoUri
-else:
- from sphinx.errors import NoUri
+from sphinx.errors import NoUri
import re
from itertools import chain
@@ -74,6 +70,12 @@ Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap',
c_namespace = ''
+#
+# Detect references to commits.
+#
+RE_git = re.compile(r'commit\s+(?P<rev>[0-9a-f]{12,40})(?:\s+\(".*?"\))?',
+ flags=re.IGNORECASE | re.DOTALL)
+
def markup_refs(docname, app, node):
t = node.astext()
done = 0
@@ -90,7 +92,8 @@ def markup_refs(docname, app, node):
RE_struct: markup_c_ref,
RE_union: markup_c_ref,
RE_enum: markup_c_ref,
- RE_typedef: markup_c_ref}
+ RE_typedef: markup_c_ref,
+ RE_git: markup_git}
if sphinx.version_info[0] >= 3:
markup_func = markup_func_sphinx3
@@ -276,6 +279,17 @@ def get_c_namespace(app, docname):
return match.group(1)
return ''
+def markup_git(docname, app, match):
+ # While we could probably assume that we are running in a git
+ # repository, we can't know for sure, so let's just mechanically
+ # turn them into git.kernel.org links without checking their
+ # validity. (Maybe we can do something in the future to warn about
+ # these references if this is explicitly requested.)
+ text = match.group(0)
+ rev = match.group('rev')
+ return nodes.reference('', nodes.Text(text),
+ refuri=f'https://git.kernel.org/torvalds/c/{rev}')
+
def auto_markup(app, doctree, name):
global c_namespace
c_namespace = get_c_namespace(app, name)
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index 4eb150bf50..e6959af254 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -127,11 +127,7 @@ def setup(app):
# Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace::
app.connect('source-read', c_markups)
-
- if (major == 1 and minor < 8):
- app.override_domain(CDomain)
- else:
- app.add_domain(CDomain, override=True)
+ app.add_domain(CDomain, override=True)
return dict(
version = __version__,
diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py
index 13e885bbd4..97166333b7 100644
--- a/Documentation/sphinx/kfigure.py
+++ b/Documentation/sphinx/kfigure.py
@@ -61,13 +61,7 @@ import sphinx
from sphinx.util.nodes import clean_astext
import kernellog
-# Get Sphinx version
-major, minor, patch = sphinx.version_info[:3]
-if major == 1 and minor > 3:
- # patches.Figure only landed in Sphinx 1.4
- from sphinx.directives.patches import Figure # pylint: disable=C0413
-else:
- Figure = images.Figure
+Figure = images.Figure
__version__ = '1.0.0'
diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 335b53df35..5d47ed4439 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,3 +1,6 @@
# jinja2>=3.1 is not compatible with Sphinx<4.0
jinja2<3.1
+# alabaster>=0.7.14 is not compatible with Sphinx<=3.3
+alabaster<0.7.14
Sphinx==2.4.4
+pyyaml
diff --git a/Documentation/sphinx/templates/kernel-toc.html b/Documentation/sphinx/templates/kernel-toc.html
index b58efa99df..41f1efbe64 100644
--- a/Documentation/sphinx/templates/kernel-toc.html
+++ b/Documentation/sphinx/templates/kernel-toc.html
@@ -12,5 +12,7 @@
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
- sbar.scrollTop = currents[currents.length - 1].offsetTop;
+ if (currents.length) {
+ sbar.scrollTop = currents[currents.length - 1].offsetTop;
+ }
--> </script>
diff --git a/Documentation/sphinx/templates/translations.html b/Documentation/sphinx/templates/translations.html
new file mode 100644
index 0000000000..8df5d42d8d
--- /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 0000000000..32c2b32b2b
--- /dev/null
+++ b/Documentation/sphinx/translations.py
@@ -0,0 +1,99 @@
+# 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):
+ 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:])
+
+ 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={
+ '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,
+ }