Skip to contentSkip to conversation

docs: Better handle kernel-doc class

PATCH New Mauro Carvalho Chehab 1 participant 3 messages May 20, 2025

Subsystems (2)
Documentation Documentation scripts
lore
Share & tools
lore

Mauro Carvalho Chehab

author
#0 lore raw

cover docs: Better handle kernel-doc class

Currently, there is an issue with kernel-doc KernelFiles class:
if one tries to add a kernel-doc tag to a non-existing file, it will produce a KeyError, as KernelFiles.msg() will try to pick a key from a non-existing file. Add a check to prevent such error.

With that, building docs with broken files will work as before(*):

	$ make htmldocs
	...
	Cannot find file ./drivers/gpio/gpiolib-acpi.c
	Cannot find file ./drivers/gpio/gpiolib-acpi.c
	No kernel-doc for file ./drivers/gpio/gpiolib-acpi.c
	...
	Documentation/arch/powerpc/htm.rst: WARNING: document isn't included in any toctree

While here, also better handle errors at the kernel-doc classes.

(*) IMO, this is the wrong behavior, but let's discuss it in separate.

Mauro Carvalho Chehab (2):
scripts: kernel-doc: prevent a KeyError when checking output
docs: kerneldoc.py: add try/except blocks for kernel-doc class errors

 Documentation/sphinx/kerneldoc.py | 21 +++++++++++++++++----
 scripts/lib/kdoc/kdoc_files.py    |  4 ++++
 2 files changed, 21 insertions(+), 4 deletions(-)
Signature · 1 line
2.49.0
author
#1 lore raw

PATCH 1/2 scripts: kernel-doc: prevent a KeyError when checking output

If a file sent to KernelFiles.msg() method doesn't exist, instead of producing a KeyError, output an error message.

Reported-by Randy Dunlap <[email protected]>
Closes https://lore.kernel.org/linux-doc/[email protected]/T/#ma43ae9d8d0995b535cf5099e5381dace0410de04 open here
Signed-off-by Mauro Carvalho Chehab <[email protected]>
---
 scripts/lib/kdoc/kdoc_files.py | 4 ++++
 1 file changed, 4 insertions(+)
scripts/lib/kdoc/kdoc_files.py +4 -0
index 630aa5ca6460..9be4a64df71d 100644
@@ -271,6 +271,10 @@ class KernelFiles():
                                       no_doc_sections)
 
             msg = ""
+            if fname not in self.results:
+                self.config.log.warning("No kernel-doc for file %s", fname)
+                continue
+
             for name, arg in self.results[fname]:
                 m = self.out_msg(fname, name, arg)
Signature · 1 line
2.49.0
author
#2 lore raw

PATCH 2/2 docs: kerneldoc.py: add try/except blocks for kernel-doc class errors

In reply to Mauro Carvalho Chehab

Replicate the same behavior as what's done with kernel-doc.pl:
continue building docs even when there are exceptions.

Signed-off-by Mauro Carvalho Chehab <[email protected]>
---
 Documentation/sphinx/kerneldoc.py | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)
Documentation/sphinx/kerneldoc.py +17 -4
index 314479718a01..4de667d4d95b 100644
@@ -278,14 +278,27 @@ class KernelDocDirective(Directive):
 
         node = nodes.section()
 
-        kfiles.parse(**self.parse_args)
-        filenames = self.parse_args["file_list"]
+        try:
+            kfiles.parse(**self.parse_args)
+            filenames = self.parse_args["file_list"]
+            msgs = kfiles.msg(**self.msg_args, filenames=filenames)
 
-        for filename, out in kfiles.msg(**self.msg_args, filenames=filenames):
+        except Exception as e:  # pylint: disable=W0703
+            logger.warning("kernel-doc '%s' processing failed with: %s" %
+                           (cmd_str(cmd), str(e)))
+
+        for filename, out in msgs:
             if self.verbose >= 1:
                 print(cmd_str(cmd))
 
-            ret = self.parse_msg(filename, node, out, cmd)
+            try:
+                ret = self.parse_msg(filename, node, out, cmd)
+
+            except Exception as e:  # pylint: disable=W0703
+                logger.warning("kernel-doc '%s' processing failed with: %s" %
+                               (cmd_str(cmd), str(e)))
+                return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
+
             if ret:
                 return ret
Signature · 1 line
2.49.0