Message-ID: <20251117133203.71b97d47@foz.lan>
Date: Mon, 17 Nov 2025 13:32:03 +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, 17 Nov 2025 12:22:48 +0100
Miguel Ojeda <miguel.ojeda.sandonis@...il.com> escreveu:

> On Mon, Nov 17, 2025 at 11:48 AM Mauro Carvalho Chehab
> <mchehab+huawei@...nel.org> wrote:
> >
> > Sure, Sphinx (including kernel-doc) build and rust doca build are
> > independent. Yet, Makefile "htmldocs" target currently does both.
> >
> > It could make sense to have a separate target if one want to build
> > them both, e.g. something like:  
> 
> My understanding (Cc'ing Carlos) is that the idea was that `htmldocs`
> built the Rust docs if possible.
> 
> I don't mind if that is changed etc., but I think it is important to
> keep the `rustdoc` target simple and focused: it is a "basic"
> operation (which is also used to lint docs too), and way faster than
> building the HTML docs, and it doesn't depend on them.

Heh, the same applies to the current usage of htmldocs - specially
when SPHINXDIRS is used, e.g. one doing, for instance:

	make SPHINXDOCS=driver-api/<subsystem>

may not be interested on building rust docs, which, on such case,
may be a lot slower than a partial build. Also, I don't think that
rustdoc currently does something similar to SPHINXDOCS.

So, at least for me, it does make sense to have separate targets
for Sphinx, Rust and both (*).

(*) now, how such targets would be named is a completely different
    question.

> Apologies if I put it perhaps a bit too tersely in my previous message
> -- everyone contributing to Rust code is supposed to rely on that
> target to test their commits, and needing the whole Sphinx setup would
> make the target way worse in practice.

Agreed.

> 
> Now, in the future, if we start relying on generating references for
> the Rust docs from the C side and things like that (which is my plan,
> but it is long term: first item in
> https://github.com/Rust-for-Linux/linux/issues/350), we may need to
> rethink things a bit (i.e. we may need to run a subset of the kernel
> normal docs to build the Rust docs), but even then ideally we should
> only introduce the minimal dependency needed.

IMO, this is a separate discussion, as you may need a different
toolset.

The way I see, for issue #350 IMO the best would be to create a 
Sphinx extension similar to:

	Documentation/sphinx/parser_yaml.py

E.g. you would create a parser_rust.py module there, which would
generate ReST output from the rust code(*). Besides allowing cross
references between Sphinx, C and Rust, this would also allow
generating epub and pdf output.

(*) In practice, teaching rustdoc how to produce ReST output.
    Alternatively, rustdoc could generate a markdown output and use
    a sphinx markdown extension at parser_rust.py, to convert from
    MD to ReST like this extension:

	https://www.sphinx-doc.org/en/master/usage/markdown.html

Besides allowing cross references between Sphinx, C and Rust, a Sphinx
extension would also allow generating epub and pdf output, removing
all extra Makefile (or wrapper) code related to rustdoc.

-

Another alternative would be to use intersphinx, but I guess
making it working would be a lot more complex - as we don't even
support it yet on our current Sphinx output.
	

Thanks,
Mauro

Powered by blists - more mailing lists