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

Mauro Carvalho Chehab
2025-06-10T08:13:37Z

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