Em Fri, 21 Jun 2019 17:51:57 -0600
Jonathan Corbet <corbet@xxxxxxx> 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!
> Signed-off-by: Jonathan Corbet <corbet@xxxxxxx>
> ---
> Documentation/conf.py | 3 +-
> Documentation/sphinx/automarkup.py | 80 ++++++++++++++++++++++++++++++
> 2 files changed, 82 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/sphinx/automarkup.py
>
> diff --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@xxxxxxx>
> +#
> +# 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
