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

[Jani Nikula <jani.nikula@linux.intel.com>]

On Tue, 15 Apr 2025, Andy Shevchenko <andriy.shevchenko@intel.com> wrote:
> 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.

kernel-doc gets run on source files for W=1 builds. See Makefile.build.

BR,
Jani.


>
>> 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.

-- 
Jani Nikula, Intel