Re: [TECH TOPIC] Kernel documentation

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

Em Mon, 20 Nov 2023 06:50:34 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> 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.

Cross references is quite useful for media docs. Having a way to
optionally disable it to speedup builds may make some sense, but
the default should be to have it enabled and producing warnings.

There is still a long-term bug on Sphinx C domain logic: it still can't
have symbols with the same name for different types. So, we have a
dozen warnings due to that when building with Sphinx version 3.1 and 
above:

	https://github.com/sphinx-doc/sphinx/pull/8313

Thanks,
Mauro