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

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

Em Tue, 10 Jun 2025 11:11:50 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

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

IMO, that happens because of the extra step introduced by ynl_gen_rst.py.

Any file renames and deletes will cause troubles. Btw, with those:

	YNL_INDEX:=$(srctree)/Documentation/networking/netlink_spec/index.rst
	YNL_RST_DIR:=$(srctree)/Documentation/networking/netlink_spec
	YNL_YAML_DIR:=$(srctree)/Documentation/netlink/specs
	YNL_TOOL:=$(srctree)/tools/net/ynl/pyynl/ynl_gen_rst.py

	YNL_RST_FILES_TMP := $(patsubst %.yaml,%.rst,$(wildcard $(YNL_YAML_DIR)/*.yaml))
	YNL_RST_FILES := $(patsubst $(YNL_YAML_DIR)%,$(YNL_RST_DIR)%, $(YNL_RST_FILES_TMP))

$(YNL_INDEX): $(YNL_RST_FILES)
        $(Q)$(YNL_TOOL) -o $@ -x

$(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL)
        $(Q)$(YNL_TOOL) -i $< -o $@

the produced ReST files aren't placed inside Documentation/output.
They're placed instead at $(srctree). This can be problematic,
specially when O= is in place.

IMO, the right solution would be to write a Sphinx extension that would
be internally calling ynl_gen_rst.py. This way, there won't be a need to
store.

There is a second option: do something similar to what we did when
media uAPI documents got migrated to Sphinx(*). The Makefile part
is at:

	Documentation/userspace-api/media/Makefile

Where generated ReST files are stored under $(BUILDDIR). We did this before 
we start writing our own Sphinx extensions. While such approach works,IMO
a Sphinx extension would be better integrated.

---

(*) the tool there ensures that the entire uAPI headers will be included
    on media documentation in a way that all symbols will have a
    cross-reference to uAPI documentation. This way, if one adds a new
    uAPI without touching docs, warnings will be generated.

> 
> Thanks,
> Akira



Thanks,
Mauro