Re: [PATCH v3 0/8] Collect documentation-related tools under /tools/docs

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Tue, 28 Oct 2025 17:15:26 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Jonathan Corbet <corbet@lwn.net> writes:
> 
> >> 3. change the core of the logic to be something like:
> >> 
> >> 	# kerneldoc_bin = env.config.kerneldoc_bin
> >> 	kerneldoc_bin = os.environ.get("KERNELDOC")
> >> 
> >> 	if not kerneldoc_bin:
> >> 	   out_style = RestFormat()
> >> 	   kfiles = KernelFiles(out_style=out_style, logger=logger)
> >> 	else:
> >> 	    print(f"Generating C documentation by running {kerneldoc_bin} binary")
> >> 
> >>    this would still allow using KERNELDOC to point to a binary
> >>    that will handle C files executed as a separate process.  
> >
> > This seems like an obvious improvement, and one that, perhaps, should go
> > in ahead of my current series in the perhaps vain hope that we're
> > finally getting to the end of the list of things I can find to break...
> >
> > I can send a patch around in the next couple of days if you don't beat
> > me to it.  
> 
> So I have that change working just fine ... only one problem.
> 
> For this to work, we have to take out the definition of KERNELDOC in the
> top-level Makefile, otherwise we'll never go the import path.  But there
> are a few other Makefiles, mostly in the DRM area, that need that
> definition.

True, DRM makefiles run kernel-doc to check for warnings within the
DRM subsystem. 

>  So I have the docs build working, but I've broken other
> things, and I think people are getting tired of me breaking things.
> 
> Possible solutions:
> 
> - Add a new FORCE_KDOC environment variable that is used instead of
>   KERNELDOC to set the program to run in the docs build.

Works for me.

> - Keep the current logic that special-cases setting KERNELDOC to
>   scripts/kernel-doc.py and really runs in the imported mode in that
>   case.

Not sure if I got what you meant. Do you mean not running the classes
but always run exec() syscall? This will likely affect build time,
and prevent further speedup optimizations. It will also duplicate
warnings if we drop the output filter logic for warnings.

> 
> - Go into retirement and let it be somebody else's problem
> 
> Anybody have any other great ideas?
> 
> Thanks,
> 
> jon