Re: sphinx-build is really slow, any way to improve that?

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Tue, 6 Sept 2022 at 08:55, Daniel P. Berrangé <berrange@redhat.com> wrote:
>>
>> On Mon, Sep 05, 2022 at 10:21:55PM +0100, Peter Maydell wrote:
>> > On Mon, 5 Sept 2022 at 20:51, Claudio Fontana <cfontana@suse.de> wrote:
>> > > when I build qemu, there is a lot of time spent at the end of the build where one cpu goes 100% on sphinx-build.
>> > >
>> > > Is there some way to parallelize that? It seems it is the current bottleneck for rebuilds for me..
>> >
>> > It's a big fat python program, so I suspect not, but
>> > maybe I'm wrong.
>>
>> It annoys me too and I've had a look at what it is doing in the past and
>> failed to find an obvious way to improve it. I fear this could be an
>> inherant limitation of the way we use sphinx to build the docs as a
>> complete manual, as compared to say treating each docs source file as
>> a distinct standalone web page.
>
> IIRC sphinx really really wants to process the whole document tree
> in one go. You can see this in the way that for example the
> HTML build process creates HTML files for the top-level rst
> files that are supposed to be only for the manpage -- it will
> suck in and process everything, not just the files reachable
> via whatever top level file you point it at.

How do other projects deal with the resulting slowness?

Could we avoid rerunning sphinx-build when documentation hasn't changed?