Re: [PATCH v5 0/2] docs: Integrate rustdoc into Rust documentation

[Carlos Bilbao]

On 1/2/23 17:53, Jonathan Corbet wrote:

> Carlos Bilbao <carlos.bilbao@xxxxxxx> writes:
>
> > Include HTML output generated with rustdoc into the Linux kernel
> > documentation on Rust.
> >
> > Carlos Bilbao:
> >   docs: Move rustdoc output, cross-reference it
> >   docs: Integrate rustdoc generation into htmldocs
> OK, so I just gave this a try...
>
> - It forces the generation of a kernel configuration, something that the
>    docs build has never done until now.  What are our changes of
>    eliminating that?


Yes, this means "make htmldocs" will require kernel .config, but only if we
want CONFIG_RUST=y. AFAIK this is a limitation of Rust in the kernel at the
moment, not something particular to this patch.


> - It did a bunch of other building, starting with objtool - again, never
>    needed for the docs build before.


Yes, building rustdoc requires building new things, no way around that
either, IMHO.


> In the end, it died with:
>
> > BINDGEN rust/bindings/bindings_generated.rs
> > Failed to run rustfmt: No such file or directory (os error 2) (non-fatal, continuing)
> >    BINDGEN rust/bindings/bindings_helpers_generated.rs
> > error: Found argument '--blacklist-type' which wasn't expected, or isn't valid in this context
> >
> > 	Did you mean '--blocklist-type'?
> Perhaps this is because I ignored the warnings about my Rust toolchain
> being too new? (Rust 1.65.0, bindgen 0.63.0).  I get that only one


Yes, it is important to have the expected Rust toolchain. You can try
running:

rustup override set $(scripts/min-tool-version.sh rustc)

there's more information about this on the Rust Quick Start [1]. It may be
annoying but you will need this for any future Rust-kernel work too.


> version is really supported, but it would be nice to fail a bit more
> gracefully if at all possible.
>
> Anyway, I've unapplied these for now; thoughts on all this?


My two cents is that these are limitations of Rust in the kernel, at least
on its current state, and so adding rustdoc to the Documentation was
going to come with them. But if someone has any ideas to make it less
painful, I'm all ears too :)


> Thanks,
>
> jon


Thanks,

Carlos


[1] 
https://github.com/Rust-for-Linux/linux/blob/rust/Documentation/rust/quick-start.rst