[PATCH 0/2] docs: Better handle kernel-doc class

[PATCH 0/2] docs: Better handle kernel-doc class

[Mauro Carvalho Chehab]

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(-)

-- 
2.49.0

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

[Mauro Carvalho Chehab]

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

Reported-by: Randy Dunlap <rdunlap@infradead.org>
Closes: https://lore.kernel.org/linux-doc/cover.1747719873.git.mchehab+huawei@kernel.org/T/#ma43ae9d8d0995b535cf5099e5381dace0410de04
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/lib/kdoc/kdoc_files.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py
index 630aa5ca6460..9be4a64df71d 100644
--- a/scripts/lib/kdoc/kdoc_files.py
+++ b/scripts/lib/kdoc/kdoc_files.py
@@ -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)
 
-- 
2.49.0

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

[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 <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/kerneldoc.py | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index 314479718a01..4de667d4d95b 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -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
 
-- 
2.49.0