I benchmarked a few different versions of sphinx-build for 'make -j128 htmldocs' (with 128 cores) and got these results:

2.4.4 -- 7m37s
3.0 -- 94m43s
4.0 -- 70m49s
5.0 -- error
6.0 -- 97m12s
7.2.6 -- 17m18s

This machine can compile a full distro kernel in like 2 minutes.

I actually really like Sphinx but this is Not Good.

@vegard surprising

@vegard yes, something is horribly wrong with Sphinx's parallelism. :(

@vegard Something weird is going on there to get numbers like that. Sphinx got a lot slower starting with 3.x, but not that much slower (about a factor of two for me).

As far as I can tell, Sphinx can only do the parsing and building of the internal tree in parallel; the HTML generation is single-threaded. So more cores only help so much. But I have no idea why you would spend over an hour waiting for something I can do in six minutes on a basic desktop machine.

@corbet @vegard

I spent a few moments on this, first trying to run sphinx-build directly on the command-line, and completely taking the kernel makefiles out of the picture.

It's impossible.

The Sphinx invocation has become so convoluted and tied to the Makefiles it reminds me of the DocBook days that we worked so hard to get rid of.

cmd_sphinx includes a sub-makefile run to convert headers to rst in perl, and whatnot. The kernel_abi extension depends on environment variables. Etc.

😔

@jani @corbet For kernel_abi I think it should be fairly straightforward to change it to do what you're doing in kerneldoc.py?

But I really don't think what happens before we get to 'sphinx-build' is that much of a problem. Convoluted, maybe, but not a huge performance issue.

@vegard @corbet

I'm not claiming it is a performance issue. But it could be a debugging issue. Case in point, how do you (trivially) show that it *isn't* a performance issue?

I'm just disappointed the documentation build turned into a Rube Goldberg machine. We specifically chose Sphinx because it's extensible, to avoid the problems we had before.

@jani @corbet Hm, I was going to suggest 'make htmldocs V=1' but that doesn't actually seem to do the right thing for some reason -- I was expecting it to print out the exact sphinx-build invocation. Although I do see it printing "Running Sphinx v4.3.2" so I know that getting to sphinx-build is less than 2-3 seconds.

@vegard @corbet

This will show you the command-line (yes, it's silly):

diff --git a/Documentation/sphinx/parallel-wrapper.sh b/Documentation/sphinx/parallel-wrapper.sh
index e54c44ce117d..2b76ef799d9b 100644
--- a/Documentation/sphinx/parallel-wrapper.sh
+++ b/Documentation/sphinx/parallel-wrapper.sh
@@ -30,4 +30,4 @@ if [ -n "$parallel" ] ; then
parallel="-j$parallel"
fi

-exec "$sphinx" $parallel "$@"
+exec /usr/bin/echo "$sphinx" $parallel "$@"

@vegard @corbet

Oh dear kernel_abi.py is worse than awful. It passes the directive argument unfiltered to shell to run scripts/get_abi.pl, so that shell parses the $srctree in the arguments.

.. kernel-abi:: $(ls>$HOME/omg);$srctree/Documentation/ABI/testing
:rst:

@jani @corbet Luckily this is also fixable 🤓

@jani Do you want to claim this, or can I submit a patch?

@vegard Go ahead!

@jani @corbet It also leaks absolute paths into the build, see e.g.: https://docs.kernel.org/admin-guide/abi-obsolete.html#file-var-lib-git-docbuild-linux-obsolete-sysfs-bus-usb or https://static.lwn.net/kerneldoc/admin-guide/abi-obsolete.html#file-stuff-k-git-kernel-obsolete-o2cb