Re: Sphinx pre v3 -- removing support

[Matthew Wilcox <willy@infradead.org>]

On Fri, Jun 03, 2022 at 03:30:29PM +0000, Adam Turner wrote:
> > 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.
> 
> Do you have the reST source behind this rendered HTML? I can then try
> and find a minimal reproducer and see if we can fix within Sphinx.

Alas, I don't.  I don't even know if this is a Sphinx bug or if it's a
bug in one of the kernel addons.  It's generated by scripts/kernel-doc
from:

/**
 * kmap_local_folio - Map a page in this folio for temporary usage
 * @folio: The folio containing the page.
 * @offset: The byte offset within the folio which identifies the page.
 *
...
 */
static inline void *kmap_local_folio(struct folio *folio, size_t offset);

I see an intermediate file in
Documentation/output/_sources/vm/highmem.rst.txt
but that doesn't include the output from scripts/kernel-doc.

This is why I've been reluctant to report it; I lack enough
understanding to be useful :-(