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

From: Carlos Bilbao
Date: Tue Jan 03 2023 - 09:07:13 EST


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