summaryrefslogtreecommitdiff
path: root/Documentation/sphinx
diff options
context:
space:
mode:
authorVegard Nossum <vegard.nossum@oracle.com>2023-10-27 14:54:20 +0300
committerJonathan Corbet <corbet@lwn.net>2023-11-17 23:13:24 +0300
commit86b17aaf2e887355e4f70dd9c4897f6a06fa9b32 (patch)
tree6839ba275120f5aa946bb2c8f81ef43bf3481b2b /Documentation/sphinx
parentd591aefc6635694293a3088b3c7401504190bbec (diff)
downloadlinux-86b17aaf2e887355e4f70dd9c4897f6a06fa9b32.tar.xz
docs: automarkup: linkify git revs
There aren't a ton of references to commits in the documentation, but they do exist, and we can use automarkup to linkify them to make them easier to follow. Use something like this to find references to commits: git grep -P 'commit.*[0-9a-f]{8,}' Documentation/ Also fix a few of these to standardize on the exact format that is already used in changelogs. Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231027115420.205279-1-vegard.nossum@oracle.com
Diffstat (limited to 'Documentation/sphinx')
-rw-r--r--Documentation/sphinx/automarkup.py20
1 files changed, 19 insertions, 1 deletions
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 06b34740bf90..acc6d55718bd 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -74,6 +74,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 +96,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 +283,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)