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

On Mon, 09 Jun 2025 16:03:32 -0600, Jonathan Corbet wrote:
> Akira Yokosawa <[email protected]> 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/[email protected]/

    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