Re: [PATCH] lkmm: docs: Put LKMM documentation into dev-tools book

Akira Yokosawa
2025-06-10T02:11:56Z

On Mon, 09 Jun 2025 16:03:32 -0600, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
>
>> Currently, LKMM docs are not included in any of kernel documentation
>> books.
>>
>> Commit e40573a43d16 ("docs: put atomic*.txt and memory-barriers.txt
>> into the core-api book") covered plain-text docs under Documentation/
>> by using the "include::" directive along with the ":literal:" option.
>>
>> As LKMM docs are not under Documentation/, the same approach would not
>> work due to the limit of the include:: directive.
>>
>> As a matter of fact, kernel documentation has an extended directive
>> by the name of "kernel-include::", which has no such limitation.
>>
>> Rather than moving LKMM docs around, use the latter with source tree's
>> abspath passed through via the "SOURCEDIR" variable which is now defined
>> in Documentation/Makefile, and make them included in the dev-tools book
>> next to KCSAN.
>
> So this fell through the cracks during my May travel, sorry.

Thank you for taking the time!

>
> I've taken a look at it now ... it adds a vast number of build warnings:
>
> Documentation/networking/netlink_spec/rt_addr.rst:28: WARNING: duplicate label rt-addr-operation-newaddr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst
> Documentation/networking/netlink_spec/rt_addr.rst:41: WARNING: duplicate label rt-addr-operation-deladdr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst
> Documentation/networking/netlink_spec/rt_addr.rst:54: WARNING: duplicate label rt-addr-operation-getaddr, other instance in /stuff/k/git/kernel/Documentation/networking/netlink_spec/rt-addr.rst
> [...]
>
> I haven't had a chance to figure out *why* it would have this particular
> bizarre effect...

I don't think those new warnings have anything to do with this patch.

This is mentioned by Paolo at:
https://lore.kernel.org/495e43ef-ae20-4dda-97c0-cb8ebe97394b@redhat.com/

My understanding is that this rename triggers rebuild of the related
doc, which in turns leads to quite a large number of htmldoc warning,
but it's really unharmful/pre-existing issue.

, and Donald said in his reply at:
https://lore.kernel.org/CAD4GDZw+Enkd2dA8f7pNxMadwURFd_tHv1sUwkXqFqxsOquHQQ@mail.gmail.com/

Yes, Documentation/Makefile goes the extra mile to only try deleting a
list of .rst files generated from the list of source .yaml files. It
would be easier to just delete
Documentation/networking/netlink_spec/*.rst which would be able to
clean up old generated files in situations like this.

HTH.

BTW, I assumed Paul would take this patch into his lkmm branch for v6.17,
once all is clear for the new uses of "..kernel-include::" with ":literal:".

Thanks,
Akira