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

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

On Mon, Sep 01, 2025 at 07:40:21PM +0100, Mark Brown wrote:
> On Mon, Sep 01, 2025 at 12:25:30PM -0600, Jonathan Corbet wrote:
> > Mark Brown <broonie@kernel.org> writes:
> 
> > >   make -j56 htmldocs  2355.99s user 141.33s system 158% cpu 26:14.86 total
> 
> > That ... is weird... it takes me a little under 3 minutes to do an
> > htmldocs build, using a capable but not stellar desktop machine.
> 
> > Which version of Sphinx are you using?  If you're not on Sphinx 8, you
> > really want to be; they finally fixed some really nasty performance
> > problems with that release.
> 
> I appear to be on version 5.3 which is what's in my distro.  I will get
> 8.1.3 when I upgrade, I don't really have any intention of manually
> installing an unpackaged copy.  Three minutes would be more reasonable,
> though without a clean build (and I guess something that errors on
> warnings so I don't actually need to look at the output myself) I'm not
> sure I'd notice any issues.

You can install it on a Python virtual env, using it only for doc builds.
Procedure is quite simple.

As Jon pointed out, from 3.x to 7.x, Sphinx had lots of performance
issues. On my 64GB RAM system, I even had to enable swap to avoid OOM
killer when testing builds with 7.x.

All of those were gone on 8.x. Build is about 3 minutes, on a big machine
and even on my 16GB i7core laptop.

Btw, on my experiences, building on Sphinx (even 8.x) with -j8 or -j24
is about the same time.

Btw, once this series is merged:

	https://lore.kernel.org/linux-doc/cover.1756740314.git.mchehab+huawei@kernel.org/T/#mdca010445a79da125b5113ca70da1b1d03a443e6

it is possible to build the docs directly at the virtual environment
without needing to enable/disable by calling directly the new 
sphinx-build-wrapper script:

	./tools/docs/sphinx-build-wrapper htmldocs -V

It will automatically search for the latest sphinx_<version> 
(or sphinx_latest) at the Kernel dir and use it for doc build. 
-V also accepts an optional argument if you want to force it to
use an specific virtual environment.


-- 
Thanks,
Mauro