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 :-(
