Message-ID: <20251124093415.679c698d@foz.lan>
Date: Mon, 24 Nov 2025 09:34:15 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
Cc: Carlos Bilbao <carlos.bilbao@...nel.org>, Linux Doc Mailing List
 <linux-doc@...r.kernel.org>, Jonathan Corbet <corbet@....net>, Mauro
 Carvalho Chehab <mchehab@...nel.org>, linux-kernel@...r.kernel.org, Miguel
 Ojeda <ojeda@...nel.org>
Subject: Re: [PATCH 0/1] fix rustdoc build detection

Em Mon, 24 Nov 2025 09:18:11 +0100
Mauro Carvalho Chehab <mchehab+huawei@...nel.org> escreveu:

> Em Mon, 24 Nov 2025 02:51:40 +0100
> Miguel Ojeda <miguel.ojeda.sandonis@...il.com> escreveu:
> 
> > On Fri, Nov 21, 2025 at 10:41 AM Mauro Carvalho Chehab
> > <mchehab+huawei@...nel.org> wrote:
> > >
> > > I'm not talking about stop using rustdoc. I'm talking about using
> > > it to output on a format that Sphinx can understand, and let Sphinx
> > > do the final output, solving cross-references.  
> > 
> > By stop using `rustdoc` I meant its "normal" (HTML) output, i.e. the
> > webpage with all its features and so on.
> 
> I see.
> 
> > The JSON support is unstable so far:
> > 
> >     https://github.com/rust-lang/rust/issues/76578
> 
> From the issue timestamps, it seems that it doesn't have a high
> priority.
> 
> > And even then, I imagine it will always still require a kernel config,
> > so that isn't an advantage either.
> 
> This doesn't seem to be an issue itself, as a new kernel config is easy 
> to add.
> 
> > Thus trying to mimic what `rustdoc` does is probably going to be a lot
> > of work to maintain, to likely get a worse result than what `rustdoc`
> > already does.
> 
> Perhaps one solution would be to write a new output plugin to make
> rustdoc produce a better output format that could be easily mapped
> by a Sphinx plugin (like producing an output on an enriched text
> format like Markdown or ReST).
> 
> I can't evaluate how easy/hard would be to do that, as I'm not
> familiar with Rust toolset.
> 
> > Something that would work without a config could be way more
> > interesting for us to integrate into Sphinx.
> 
> At Sphinx side, it won't be hard to pick references from rustdoc.
> 
> At kernel_include extension:
> 
> 	https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/sphinx/kernel_include.py
> 
> I added a logic there to detect unsolved cross-references.
> 
> Currently, it just warns about unsolved references, but it won't 
> be hard to modify a similar logic to solve it, pointing to a
> rustdoc reference (if those are stable enough).
> 
> Doing the reverse can be trickier, though: internally, Sphinx
> maps them via a C domain. The output plugin (html, pdf, ...)
> is what converts such reference into an html (or pdf) tag.
> Such mapping is version dependent.
> 
> There was a major rewrite at eh C domain on Sphinx 3.0 which
> changed such mapping, but other versions may have changed it as well.
> 
> Also, there is an open issue that will likely change it once
> fixed:
> 
> 	https://github.com/sphinx-doc/sphinx/issues/7819
> 	https://github.com/sphinx-doc/sphinx/issues/8241
> 
> (last one closed as duplicate of #7819)
> 
> So, creating cross-references from rustdoc to Sphinx could
> be tricky and hard to maintain, as it may require some checks
> at rust/rustdoc side to verify Sphinx version.

In time:

by "rust/rustdoc side" I mean the cross-reference solver that
would run inside the Makefile target that will be called after
building Sphinx docs. 

It will likely be external tools inside the Kernel tree to identify
Sphinx and docutils versions, rust/rustodoc version, and do whatever
other check would be needed to detect the tags format and modify
the produced html output for the hyperlinks to work.


Thanks,
Mauro

Powered by blists - more mailing lists