bybrooklyn/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-05-05 23:05:25 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: kdoc: remove support for an external kernel-doc from sphinx

Browse Source 
The ability to build the docs with an external kernel-doc program involves
some truly confusing logic and complicates the task of moving kernel-doc
out of scripts/.  But this feature is not useful for normal documentation
builds, and the external kernel-doc can always be run by hand when it needs
debugging.  So just remove that feature and make life easier.

There is still a bunch of logic to build a command line that we never use;
the idea is to be able to output it, but I'm not sure if that is worth
keeping.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <a97a8361546648906344457a7e92e4db533048a9.1768823489.git.mchehab+huawei@kernel.org>
This commit is contained in:
Jonathan Corbet
2026-01-19 13:05:00 +01:00
parent 6cc45ee5df
commit 24f984aa11
1 changed files with 6 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
Documentation/sphinx/kerneldoc.py
View File

@@ -190,35 +190,7 @@ class KernelDocDirective(Directive):
return cmd
def run_cmd(self, cmd):
"""
Execute an external kernel-doc command.
"""
env = self.state.document.settings.env
node = nodes.section()
p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
out, err = p.communicate()
out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
if p.returncode != 0:
sys.stderr.write(err)
logger.warning("kernel-doc '%s' failed with return code %d"
% (" ".join(cmd), p.returncode))
return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
elif env.config.kerneldoc_verbosity > 0:
sys.stderr.write(err)
filenames = self.parse_args["file_list"]
for filename in filenames:
self.parse_msg(filename, node, out, cmd)
return node.children
def parse_msg(self, filename, node, out, cmd):
def parse_msg(self, filename, node, out):
"""
Handles a kernel-doc output for a given file
"""
@@ -244,7 +216,7 @@ class KernelDocDirective(Directive):
self.do_parse(result, node)
def run_kdoc(self, cmd, kfiles):
def run_kdoc(self, kfiles):
"""
Execute kernel-doc classes directly instead of running as a separate
command.
@@ -258,23 +230,17 @@ class KernelDocDirective(Directive):
filenames = self.parse_args["file_list"]
for filename, out in kfiles.msg(**self.msg_args, filenames=filenames):
self.parse_msg(filename, node, out, cmd)
self.parse_msg(filename, node, out)
return node.children
def run(self):
global kfiles
cmd = self.handle_args()
if self.verbose >= 1:
logger.info(cmd_str(cmd))
try:
if kfiles:
return self.run_kdoc(cmd, kfiles)
else:
return self.run_cmd(cmd)
return self.run_kdoc(kfiles)
except Exception as e: # pylint: disable=W0703
logger.warning("kernel-doc '%s' processing failed with: %s" %
(cmd_str(cmd), pformat(e)))
@@ -286,15 +252,8 @@ class KernelDocDirective(Directive):
def setup_kfiles(app):
global kfiles
kerneldoc_bin = app.env.config.kerneldoc_bin
if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"):
print("Using Python kernel-doc")
out_style = RestFormat()
kfiles = KernelFiles(out_style=out_style, logger=logger)
else:
print(f"Using {kerneldoc_bin}")
out_style = RestFormat()
kfiles = KernelFiles(out_style=out_style, logger=logger)
def setup(app):