docs: Fix kernel-doc -Werror and moves it to tools/docs

[PATCH 0/9] docs: Fix kernel-doc -Werror and moves it to tools/docs

Posted by Mauro Carvalho Chehab 2 weeks, 5 days ago

Hi Jon,

After a restful weekend and revisiting both yours and my series,
I'm opting to send a patch series merging both into one:

- The first 4 patches are from my series (no changes since v5):
    https://lore.kernel.org/linux-doc/cover.1768642102.git.mchehab+huawei@kernel.org/T/#m81211c0ff38bbaa82b8b0b6606f242ccc0c2a9ac

- It follows by the 2 patches from your renaming series:
    https://lore.kernel.org/linux-doc/20260119111745.4694546b@foz.lan/T/#m51099c31a99dccccdb4d17cbaadc818e9e4df8c4

  with the fix I proposed for kernel-doc to find its libraries

I added 3 patches afterwards:

  - patch 5: move possible return values from docstring to helper message;
  - patch 6: improve MsgFormatter description;
  - patch 7: moves kerneldoc_bin from conf.py to the sphinx/kerneldoc.py
    (this is now just a debugging message - no need to pick it from env)

IMO, this series is ready to be merged.

NOTE:
    I didn't rename kernel-doc to kernel_doc.py nor added any symlinks.
    If we want some day to use sphinx autoparse extension, we can do it
    later. I guess we can also revisit it during -rc period, if needed.

Regards,
Mauro

Jonathan Corbet (2):
  docs: kdoc: remove support for an external kernel-doc from sphinx
  docs: kdoc: move kernel-doc to tools/docs

Mauro Carvalho Chehab (7):
  docs: kdoc: fix logic to handle unissued warnings
  docs: kdoc: avoid error_count overflows
  docs: kdoc: ensure that comments are using our coding style
  docs: kdoc: some fixes to kernel-doc comments
  docs: kdoc: move the return values to the helper message
  docs: kdoc: improve description of MsgFormatter
  docs: conf.py: get rid of the now unused kerneldoc_bin env var

 Documentation/conf.py                         |  4 -
 Documentation/doc-guide/kernel-doc.rst        |  8 +-
 Documentation/kbuild/kbuild.rst               |  2 +-
 Documentation/process/coding-style.rst        |  2 +-
 Documentation/sphinx/kerneldoc.py             | 60 +++----------
 .../it_IT/doc-guide/kernel-doc.rst            |  8 +-
 .../sp_SP/process/coding-style.rst            |  2 +-
 .../zh_CN/doc-guide/kernel-doc.rst            | 10 +--
 .../translations/zh_CN/kbuild/kbuild.rst      |  2 +-
 .../zh_CN/process/coding-style.rst            |  2 +-
 .../zh_TW/process/coding-style.rst            |  2 +-
 MAINTAINERS                                   |  2 -
 Makefile                                      |  2 +-
 drivers/gpu/drm/i915/Makefile                 |  2 +-
 scripts/kernel-doc                            |  1 -
 tools/docs/find-unused-docs.sh                |  2 +-
 .../kernel-doc.py => tools/docs/kernel-doc    | 89 ++++++++++++-------
 tools/docs/sphinx-build-wrapper               |  2 +-
 tools/lib/python/kdoc/kdoc_parser.py          | 35 ++++++--
 19 files changed, 120 insertions(+), 117 deletions(-)
 delete mode 120000 scripts/kernel-doc
 rename scripts/kernel-doc.py => tools/docs/kernel-doc (88%)

-- 
2.52.0

Re: [PATCH 0/9] docs: Fix kernel-doc -Werror and moves it to tools/docs

Posted by Jonathan Corbet 2 weeks, 3 days ago

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Hi Jon,
>
> After a restful weekend and revisiting both yours and my series,
> I'm opting to send a patch series merging both into one:
>
> - The first 4 patches are from my series (no changes since v5):
>     https://lore.kernel.org/linux-doc/cover.1768642102.git.mchehab+huawei@kernel.org/T/#m81211c0ff38bbaa82b8b0b6606f242ccc0c2a9ac
>
> - It follows by the 2 patches from your renaming series:
>     https://lore.kernel.org/linux-doc/20260119111745.4694546b@foz.lan/T/#m51099c31a99dccccdb4d17cbaadc818e9e4df8c4
>
>   with the fix I proposed for kernel-doc to find its libraries
>
> I added 3 patches afterwards:
>
>   - patch 5: move possible return values from docstring to helper message;
>   - patch 6: improve MsgFormatter description;
>   - patch 7: moves kerneldoc_bin from conf.py to the sphinx/kerneldoc.py
>     (this is now just a debugging message - no need to pick it from env)
>
> IMO, this series is ready to be merged.

Patch 7 adds a new warning:

  WARNING: unknown config value 'kerneldoc_bin' in override, ignoring

It needs to be taken out of sphinx-build-wrapper; I've appended the
following patch to the series to deal with it.  I think I'll go ahead
and tack on a patch putting in the scripts/kernel-doc symlink, then I
guess it's ready to go.

Thanks,

jon

From 4a3efd128f7da996b677151790d043ec44a00561 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <corbet@lwn.net>
Date: Tue, 20 Jan 2026 15:50:38 -0700
Subject: [PATCH] docs: sphinx-build-wrapper: stop setting kerneldoc_bin for
 Sphinx

Now that the Sphinx build does not use the kerneldoc_bin configuration
variable, we shouldn't try to set it in the build wrapper or we get a nifty
warning:

  WARNING: unknown config value 'kerneldoc_bin' in override, ignoring

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 tools/docs/sphinx-build-wrapper | 1 -
 1 file changed, 1 deletion(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index cb2a5005e633..9f1ae1485f84 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -750,7 +750,6 @@ class SphinxBuilder:
 
             build_args = args + [
                 "-d", doctree_dir,
-                "-D", f"kerneldoc_bin={kerneldoc}",
                 "-D", f"version={self.kernelversion}",
                 "-D", f"release={self.kernelrelease}",
                 "-D", f"kerneldoc_srctree={self.srctree}",
-- 
2.52.0

Re: [PATCH 0/9] docs: Fix kernel-doc -Werror and moves it to tools/docs

Posted by Mauro Carvalho Chehab 2 weeks, 3 days ago

Hi Jon,

On Tue, 20 Jan 2026 15:56:48 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Hi Jon,
> >
> > After a restful weekend and revisiting both yours and my series,
> > I'm opting to send a patch series merging both into one:
> >
> > - The first 4 patches are from my series (no changes since v5):
> >     https://lore.kernel.org/linux-doc/cover.1768642102.git.mchehab+huawei@kernel.org/T/#m81211c0ff38bbaa82b8b0b6606f242ccc0c2a9ac
> >
> > - It follows by the 2 patches from your renaming series:
> >     https://lore.kernel.org/linux-doc/20260119111745.4694546b@foz.lan/T/#m51099c31a99dccccdb4d17cbaadc818e9e4df8c4
> >
> >   with the fix I proposed for kernel-doc to find its libraries
> >
> > I added 3 patches afterwards:
> >
> >   - patch 5: move possible return values from docstring to helper message;
> >   - patch 6: improve MsgFormatter description;
> >   - patch 7: moves kerneldoc_bin from conf.py to the sphinx/kerneldoc.py
> >     (this is now just a debugging message - no need to pick it from env)
> >
> > IMO, this series is ready to be merged.  
> 
> Patch 7 adds a new warning:
> 
>   WARNING: unknown config value 'kerneldoc_bin' in override, ignoring
> 
> It needs to be taken out of sphinx-build-wrapper; I've appended the
> following patch to the series to deal with it. 

True, thanks for checking it!

> I think I'll go ahead
> and tack on a patch putting in the scripts/kernel-doc symlink, then I
> guess it's ready to go.

Go ahead. Yeah, I think that, with such changes, this series is
ready to go.
> 
> Thanks,
> 
> jon
> 
> From 4a3efd128f7da996b677151790d043ec44a00561 Mon Sep 17 00:00:00 2001
> From: Jonathan Corbet <corbet@lwn.net>
> Date: Tue, 20 Jan 2026 15:50:38 -0700
> Subject: [PATCH] docs: sphinx-build-wrapper: stop setting kerneldoc_bin for
>  Sphinx
> 
> Now that the Sphinx build does not use the kerneldoc_bin configuration
> variable, we shouldn't try to set it in the build wrapper or we get a nifty
> warning:
> 
>   WARNING: unknown config value 'kerneldoc_bin' in override, ignoring
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> ---
>  tools/docs/sphinx-build-wrapper | 1 -
>  1 file changed, 1 deletion(-)
> 
> diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
> index cb2a5005e633..9f1ae1485f84 100755
> --- a/tools/docs/sphinx-build-wrapper
> +++ b/tools/docs/sphinx-build-wrapper
> @@ -750,7 +750,6 @@ class SphinxBuilder:
>  
>              build_args = args + [
>                  "-d", doctree_dir,
> -                "-D", f"kerneldoc_bin={kerneldoc}",
>                  "-D", f"version={self.kernelversion}",
>                  "-D", f"release={self.kernelrelease}",
>                  "-D", f"kerneldoc_srctree={self.srctree}",

Thanks,
Mauro