Re: [TECH TOPIC] Kernel documentation - update and future directions

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

Em Fri, 22 Aug 2025 16:55:51 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> The last year has seen a massive amount of work in our documentation
> build infrastructure and continuous improvement in the docs themselves.
> This session will provide a brief update of what has happened recently,
> followed by discussion on what we want to do next.  How would we like
> our documentation to evolve in the next year or three?

Sounds a nice topic. Hopefully we'll have the improvements at the doc
build infrastructure before the Kernel Summit. From my side, I'd like
to keep finishing the cleanups at the Sphinx extensions, removing some
hacks that were introduced with time, and simplifying the doc Makefile.

So, for this year I expect that the entire doc build to be done
entirely in Python. For the next year, I think we can do some cleanups
at the conf.py, which has grown over time, moving the dynamic pieces
to a sphinx-build-wrapper code. I sent already a first version for it,
and I working now on a second version for the patchset.

For the next year, I guess we can focus (from the docs build side) on
a way to get rid of broken cross-references. We have a lot of them,
but they're currently hidden as by default, Sphinx doesn't report them
anymore.

I wrote already, as part of the kernel-include Sphinx extension, a logic
capable of discovering them and capable of propose similar references.
I'm  thinking that this could better fit in the future as a separate
extension.

Thanks,
Mauro