Re: [TECH TOPIC] Kernel documentation

[Jonathan Corbet <corbet@lwn.net>]

Vegard Nossum <vegard.nossum@oracle.com> writes:

> (We already exchanged on this topic, but repeating it for the list:)
>
> On 20/06/2023 21:30, Jonathan Corbet wrote:
>> Jani Nikula <jani.nikula@intel.com> writes:
>> 
>>> It should be more feasible to build the documentation. Make it
>>> faster,
>
> When using PyPy instead of CPython to run Sphinx, I see a 22%
> performance improvement on the kernel documentation, which is not
> insignificant.

That is nice, but we can't really assume that everybody building the
docs has pypy around.

>> A while back, I went into Sphinx with a hatchet and managed to take 
>> about 20% off the build time.  The C domain stuff builds a data 
>> structure of incredible complexity, then just tosses much of it
>> away. I've never had the time to figure out why they do that or to
>> try to get my hack job into a condition where I'd be willing to show
>> it to my dog, much less the Sphinx developers.
>
> I also profiled the documentation build some weeks ago and came to the
> same conclusion: around 40% of the time is spent inside resolve_xref(),
> the exact same C domain stuff you mentioned.
>
> The gcc project/documentation has the same problem, albeit in the C++
> domain code, there is an open ticket for it:
>
>    https://github.com/sphinx-doc/sphinx/issues/10966
>
> If we're really not using the functionality provided by the C domain
> code, maybe instead of ripping it out we could provide something like a
> conf.py toggle to disable it? (The idea being that the patch would be
> smaller and more acceptable upstream...)

Ah but we are - it's how we generate all of the cross-references in the
built docs.  My sense, from a couple of years ago though was that parts
of that code aren't used by *anybody*.  But I didn't feel that I'd
understood it well enough to make a proper patch.  I'd really like to
get back to that.

Thanks,

jon