Re: [PATCH 1/3] Docs: An initial automarkup extension for sphinx
From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Date: 2019-06-22 01:00:53
Also in:
lkml
Subsystem:
documentation, documentation scripts, the rest · Maintainers:
Jonathan Corbet, Mauro Carvalho Chehab, Linus Torvalds
Em Fri, 21 Jun 2019 17:51:57 -0600 Jonathan Corbet [off-list ref] escreveu:
Rather than fill our text files with :c:func:`function()` syntax, just do the markup via a hook into the sphinx build process.
Didn't test it, but it sounds a way nicer than the past version!
quoted hunk ↗ jump to hunk
Signed-off-by: Jonathan Corbet <corbet@lwn.net> --- Documentation/conf.py | 3 +- Documentation/sphinx/automarkup.py | 80 ++++++++++++++++++++++++++++++ 2 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 Documentation/sphinx/automarkup.pydiff --git a/Documentation/conf.py b/Documentation/conf.py index 7ace3f8852bd..a502baecbb85 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py@@ -34,7 +34,8 @@ needs_sphinx = '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', + 'kfigure', 'sphinx.ext.ifconfig', 'automarkup'] # The name of the math extension changed on Sphinx 1.4 if (major == 1 and minor > 3) or (major > 1):diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py new file mode 100644 index 000000000000..14b09b5d145e --- /dev/null +++ b/Documentation/sphinx/automarkup.py@@ -0,0 +1,80 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright 2019 Jonathan Corbet <corbet@lwn.net> +# +# Apply kernel-specific tweaks after the initial document processing +# has been done. +# +from docutils import nodes +from sphinx import addnodes +import re + +# +# Regex nastiness. Of course. +# Try to identify "function()" that's not already marked up some +# other way. Sphinx doesn't like a lot of stuff right after a +# :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last +# bit tries to restrict matches to things that won't create trouble. +# +RE_function = re.compile(r'([\w_][\w\d_]+\(\))') + +# +# The DVB docs create references for these basic system calls, leading +# to lots of confusing links. So just don't link them. +# +Skipfuncs = [ 'open', 'close', 'write' ]
and yeah, of course, if there's something weird, it has to be at the media docs :-) Btw, if I'm not mistaken, we do the same for ioctl. I'm wandering if this could also handle the Documentation/* auto-replace. The patch snipped I did (against your past version is enclosed).
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 39c8f4d5af82..60dad596c790 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py@@ -9,6 +9,7 @@ from __future__ import print_function import re import sphinx +#import sys # Just for debug # # Regex nastiness. Of course.
@@ -31,10 +32,26 @@ RE_literal = re.compile(r'^(\s*)(.*::\s*|\.\.\s+code-block::.*)$') # RE_whitesp = re.compile(r'^(\s*)') +# +# Get a documentation reference +# +RE_doc_links = re.compile(r'\bDocumentation/([\w\d\-\_\/]+)\.rst\b') + +# +# Doc link false-positives +# +RE_false_doc_links = re.compile(r':ref:`\s*Documentation/[\w\d\-\_\/]+\.rst') + def MangleFile(app, docname, text): ret = [ ] previous = '' literal = False + + rel_dir = '' + + for depth in range(0, docname.count('/')): + rel_dir += "../" + for line in text[0].split('\n'): # # See if we might be ending a literal block, as denoted by
@@ -63,7 +80,18 @@ def MangleFile(app, docname, text): # Normal line - perform substitutions. # else: - ret.append(RE_function.sub(r'\1:c:func:`\2`\3', line)) +# new_line = RE_function.sub(r'\1:c:func:`\2`\3', line) + new_line = line + + if not RE_false_doc_links.search(new_line): + new_line = RE_doc_links.sub(r':doc:`' + rel_dir + r'\1`', new_line) + + # # Just for debug - should be removed on production + # if new_line != line: + # print ("===>" + new_line, file=sys.stderr) + + ret.append(new_line) + # # Might we be starting a literal block? If so make note of # the fact.
Thanks, Mauro