Re: [PATCH 0/1] fix rustdoc build detection

[Mauro Carvalho Chehab]

Em Tue, 18 Nov 2025 23:02:35 +0100
Miguel Ojeda <miguel.ojeda.sandonis@xxxxxxxxx> escreveu:

> On Mon, Nov 17, 2025 at 1:32 PM Mauro Carvalho Chehab
> <mchehab+huawei@xxxxxxxxxx> wrote:
> >
> > 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.  
> 
> If you mean building the Rust docs introduces extra work for people
> building the HTML docs when that happens automatically, then yeah,
> definitely.
> 
> Perhaps it could be skipped depending on what folders are requested.

Yeah, that sounds a good approach: teach rustdoc target to handle
SPHINXDOCS. If it is empty (or just ".") handle the same way as
today. Otherwise, do a partial doc build or skip when it doesn't
make sense.

> 
> > E.g. you would create a parser_rust.py module there, which would
> > generate ReST output from the rust code(*).  
> 
> To clarify, the idea of the "external references map file" in that
> issue isn't to stop using `rustdoc`, 

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.

> but rather to allow `rustdoc` to
> have (at least) the references to C items (e.g. a link to the rendered
> `printk` docs at least to the source code where it is defined). In
> other words, it is about allowing developrers to just write something
> like [`printk()`] and the system would figure out how to link to the
> right docs automatically.
> 
> We don't plan to stop using `rustdoc` -- its output is specialized for
> Rust which makes it quite nice.
> 
> `rustdoc` can export JSON and that should be possible to use easily
> from a Sphinx plugin without having to parse Rust from scratch, to at
> least get some degree of Sphinx support. 

There is a JSON Sphinx plugin (although I never used - no idea if
it would do what it is needed):
	https://sphinx-jsonschema.readthedocs.io/en/latest/

If this won't work, I guess it wouldn't be hard to use parser_yaml.py as
an example to write a new plugin to handle rustdoc JSON output.

> That would be nice for the
> other outputs support like PDF as you mention, yeah, as well as having
> independent-to-the-config docs. We discussed it a few times, but it
> has never been a high priority, especially since `rustdoc` does its
> job quite well.

Thanks,
Mauro