Re: [PATCH] kbuild: Do not run kernel-doc when building external modules

Mauro Carvalho Chehab
2026-02-04T10:22:28Z

On Wed, Feb 04, 2026 at 12:39:03AM -0700, Nathan Chancellor wrote:
> Hi Masahiro,
>
> Good to see you around.
>
> On Wed, Feb 04, 2026 at 04:02:10PM +0900, Masahiro Yamada wrote:
> > On Sun, Feb 1, 2026 at 12:15 AM Nicolas Schier <nsc@kernel.org> wrote:
> > >
> > > On Fri, 30 Jan 2026 14:37:47 -0700, Nathan Chancellor wrote:
> > > > After commit 778b8ebe5192 ("docs: Move the python libraries to
> > > > tools/lib/python"), building an external module with any value of W=
> > > > against the output of install-extmod-build fails with:
> > > >
> > > > $ make -C /usr/lib/modules/6.19.0-rc7-00108-g4d310797262f/build M=$PWD W=1
> > > > make: Entering directory '/usr/lib/modules/6.19.0-rc7-00108-g4d310797262f/build'
> > > > make[1]: Entering directory '...'
> > > > CC [M] ...
> > > > Traceback (most recent call last):
> > > > File "/usr/lib/modules/6.19.0-rc7-00108-g4d310797262f/build/scripts/kernel-doc.py", line 339, in <module>
> > > > main()
> > > > ~~~~^^
> > > > File "/usr/lib/modules/6.19.0-rc7-00108-g4d310797262f/build/scripts/kernel-doc.py", line 295, in main
> > > > from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415
> > > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > > ModuleNotFoundError: No module named 'kdoc'
> > > >
> > > > [...]
> > >
> > > Applied to kbuild/linux.git (kbuild-fixes-unstable), thanks!
> >
> >
> > I believe this is a wrong direction to go.
> >
> > Since kernel-doc is a part of Kbuild,
> > all dependent libraries should exist under scripts/.
>
> Is this around the recent moves such as 778b8ebe5192? I guess Kbuild was
> never consulted on that change and I missed eba6ffd126cd, despite being
> CC'd, so that is on me.
>
> I did wonder if it was worth it to package these files in a previous
> change but Mauro seemed somewhat opposed to it (but maybe I
> misinterpreted something):
>
> https://lore.kernel.org/20260130063056.72fbe458@foz.lan/

Not really opposed. The point is that, on a normal run, kernel-doc
is executed with -none, to check if are there a trouble with the
kernel-doc markup (there's a kconfig option for such purpose).
Also, it is not the only tool that it is executed on such case,
on a normal build. See docs/Makefile (*):

ifneq ($(MAKECMDGOALS),cleandocs)
# Check for broken documentation file references
ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
$(shell $(srctree)/tools/docs/documentation-file-ref-check --warn)
endif

# Check for broken ABI files
ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
$(shell $(srctree)/tools/docs/get_abi.py --dir $(srctree)/Documentation/ABI validate)
endif
endif

(*) The only difference is that kernel-doc call is currently sitting
at scripts/Makefile.build. Perhaps it could make sense to move
it to docs/Makefile.

-

I think it is not worth running any such documentation-validation-tools
when doing OOT driver builds, as their goal is to ensure a good
quality of documentation within the Kernel, and OOT drivers usually
have a lot more problems than just documentation, but it is up to you.
I'm ok with either solution.

> Perhaps tools/docs could be moved to scripts/docs and tools/lib/python
> could be moved to just lib/python to have everything live logically
> outside of tools/ and make it easier to package?

The idea of moving it out of scripts is because scripts became
a no-man's land, with lots of mixed stuff. From my side, I don't
care much about its location, provided that the path is very short.

-

That's said, if you want htmldocs/mandocs/... targets to work
with OOT builds, you don't really need kernel-doc executable,
as Sphinx uses kdoc libraries directly. Yet, you need a lot
more:

1) tools executed by docs/Makefile:

tools/docs/sphinx-build-wrapper
tools/docs/sphinx-pre-install

2) Sphinx config and extensions:

Documentation/conf.py
Documentation/sphinx/
Documentation/sphinx-includes/
Documentation/sphinx-static/

3) Libraries used by sphinx-build-wrapper and sphinx extensions:

tools/lib/python/jobserver.py
tools/lib/python/abi/
tools/lib/python/feat/
tools/lib/python/kdoc/

You can also install optional command line tools, which
are helpful to run the code inside abi/feat/kdoc outside
Sphinx build:

tools/docs/kernel-doc
tools/docs/get_abi.py
tools/docs/get_feat.py
tools/docs/parse-headers.py

Regards,
Mauro