Re: Sphinx pre v3 -- removing support

[Jonathan Corbet <corbet@lwn.net>]

Matthew Wilcox <willy@infradead.org> writes:

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

This is almost certainly our bug, not something in Sphinx.

You can see what our kerneldoc script is generating with a simple:

  scripts/kernel-doc include/linux/highmem.h

Within the output, you'll find the markup for the function in question:

.. c:function:: void * kmap_local_folio (struct folio *folio, size_t offset)

   Map a page in this folio for temporary usage

I am thinking that our automarkup module is getting confused by the
'struct folio' in the prototype there; will try to dig further shortly.

Thanks,

jon