Re: [PATCH v3 00/33] Implement kernel-doc in Python

[Andy Shevchenko <andriy.shevchenko@intel.com>]

On Tue, Apr 15, 2025 at 10:01:04AM +0300, Andy Shevchenko wrote:
> On Mon, Apr 14, 2025 at 09:17:51AM -0600, Jonathan Corbet wrote:
> > Andy Shevchenko <andriy.shevchenko@intel.com> writes:
> > > On Wed, Apr 09, 2025 at 12:30:00PM -0600, Jonathan Corbet wrote:
> > >> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> > >> 
> > >> > This changeset contains the kernel-doc.py script to replace the verable
> > >> > kernel-doc originally written in Perl. It replaces the first version and the
> > >> > second series I sent on the top of it.
> > >> 
> > >> OK, I've applied it, looked at the (minimal) changes in output, and
> > >> concluded that it's good - all this stuff is now in docs-next.  Many
> > >> thanks for doing this!
> > >> 
> > >> I'm going to hold off on other documentation patches for a day or two
> > >> just in case anything turns up.  But it looks awfully good.
> > >
> > > This started well, until it becomes a scripts/lib/kdoc.
> > > So, it makes the `make O=...` builds dirty *). Please make sure this doesn't leave
> > > "disgusting turd" )as said by Linus) in the clean tree.
> > >
> > > *) it creates that __pycache__ disaster. And no, .gitignore IS NOT a solution.
> > 
> > If nothing else, "make cleandocs" should clean it up, certainly.
> > 
> > We can also tell CPython to not create that directory at all.  I'll run
> > some tests to see what the effect is on the documentation build times;
> > I'm guessing it will not be huge...
> 
> I do not build documentation at all, it's just a regular code build that leaves
> tree dirty.
> 
> $ python3 --version
> Python 3.13.2
> 
> It's standard Debian testing distribution, no customisation in the code.
> 
> To reproduce.
> 1) I have just done a new build to reduce the churn, so, running make again does nothing;
> 2) The following snippet in shell shows the issue
> 
> $ git clean -xdf
> $ git status --ignored
> On branch ...
> nothing to commit, working tree clean
> 
> $ make LLVM=-19 O=.../out W=1 C=1 CF=-D__CHECK_ENDIAN__ -j64
> make[1]: Entering directory '...'
>   GEN     Makefile
>   DESCEND objtool
>   CALL    .../scripts/checksyscalls.sh
>   INSTALL libsubcmd_headers
> .pylintrc: warning: ignored by one of the .gitignore files
> Kernel: arch/x86/boot/bzImage is ready  (#23)
> make[1]: Leaving directory '...'
> 
> $ touch drivers/gpio/gpiolib-acpi.c
> 
> $ make LLVM=-19 O=.../out W=1 C=1 CF=-D__CHECK_ENDIAN__ -j64
> make[1]: Entering directory '...'
>   GEN     Makefile
>   DESCEND objtool
>   CALL    .../scripts/checksyscalls.sh
>   INSTALL libsubcmd_headers
> ...
>   OBJCOPY arch/x86/boot/setup.bin
>   BUILD   arch/x86/boot/bzImage
> Kernel: arch/x86/boot/bzImage is ready  (#24)
> make[1]: Leaving directory '...'
> 
> $ git status --ignored
> On branch ...
> Untracked files:
>   (use "git add <file>..." to include in what will be committed)
> 	scripts/lib/kdoc/__pycache__/
> 
> nothing added to commit but untracked files present (use "git add" to track)

FWIW, I repeated this with removing the O=.../out folder completely, so it's
fully clean build. Still the same issue.

And it appears at the very beginning of the build. You don't need to wait to
have the kernel to be built actually.

> It's 100% reproducible on my side. I am happy to test any patches to fix this.
> It's really annoying "feature" for `make O=...` builds. Also note that
> theoretically the Git worktree may be located on read-only storage / media
> and this can induce subtle issues.

-- 
With Best Regards,
Andy Shevchenko