Re: Sphinx pre v3 -- removing support

[Matthew Wilcox <willy@infradead.org>]

On Fri, Jun 03, 2022 at 08:21:39AM -0600, Jonathan Corbet wrote:
> Adam Turner <aaturnerpython@outlook.com> writes:
> 
> > Hi,
> >
> > I was pointed in the direction of this mailing list by Jani Nikula in
> > [1]_, who said:
> >
> >> Thanks for the ping. I was heavily involved in the early days of
> >> converting the kernel to use Sphinx, but I haven't closely followed
> >> the recent developments. Basically I think I'd also be inclined to
> >> push for much higher minimum Sphinx version requirements than what
> >> the kernel currently has. The minimum at the moment is v1.7.9 
> >> (or v2.4.4 for PDF). It's difficult to maintain support for a wide
> >> range of Sphinx versions. Perhaps the best bet would be to mail the
> >> kernel documentation list at linux-doc@vger.kernel.org and Cc 
> >> Jonathan Corbet corbet@lwn.net to try to reach an understanding on
> >> the recommended minimum version and version ranges that makes sense
> >> for both parties to support. HTH.
> >
> > This email is an attempt to do that. 
> >
> > From Sphinx's perspective, we'd like to remove long-deprecated code.
> > What is a good solution here for both sides? The intertial option is
> > for us to delay the deprecation by another major version (removal is
> > currently scheduled for Sphinx 6 (2023-05), and we are currently 
> > releasing a major version every May.
> >
> > Jani reports that you still require Sphinx 1.7.9 -- I have no 
> > investment in the documentation development of the kernel, but he
> > rightly notes that is quite an old version -- released 3 years and 9
> > months ago.
> >
> > Please would you let me know if there is anything required on our
> > (Sphinx's) end that would let us drop the "pre v3" support gracefully.
> 
> We've been meaning to raise the minimum version for a bit.  Going to v3
> might be a bit of a stretch, though.  I still do most of my test builds
> with 2.4.3 just because Sphinx got so....much........slower with 3.0.
> I've not yet had a chance to try out 5.0 to see if that helps things,
> that's on my list to do soon.

We'd need to coordinate with kernel.org's automated build of the
documentation.  I believe Konstantin handles that.  With pip, I imagine
he can install whatever version is needed.

There's a bug I've been meaning to track down & report where _some_ links
are broken when building with the Sphinx natively installed on my system
(Debian 4.3.2-1).  I haven't bothered because (a) life is short and (b)
it's not affecting the kernel.org build.  If we're going to ask
kernel.org to move to a newer version of Sphinx, we should make sure
that the links won't be broken on whatever version we pick.

An example:
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">kmap_local_folio</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.kmap_local_folio" title="folio"><span class="n"><span class="pre">folio</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">folio</span></span>, <span class="n"><span class="pre">size_t</span></span><span class="w"> </span><span class="n"><span class="pre">offset</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.kmap_local_folio" title="Permalink to this definition">¶</a><br /></dt>

Other than that being a big pile of html, that <a href> around 'folio'
should be a link to struct folio and not back to the c.kmap_local_folio
anchor.

I appreciate this is not a great bug report, but I find the entire
build system beyond my comprehension.