On 11/28/22 16:23, Jonathan Corbet wrote:
Carlos Bilbao <carlos.bilbao@xxxxxxx> writes:
Include HTML output generated from rustdoc into the Linux kernel
documentation on Rust. Add Makefile target `make htmlrust` to combine
make htmldocs and the generation of Rust documentation.
Signed-off-by: Carlos Bilbao <carlos.bilbao@xxxxxxx>
---
Documentation/Makefile | 11 +++++++++++
Documentation/rust/index.rst | 1 +
Documentation/rust/rustdoc.rst | 10 ++++++++++
Makefile | 2 +-
4 files changed, 23 insertions(+), 1 deletion(-)
create mode 100644 Documentation/rust/rustdoc.rst
Thanks for doing this. I do have a number of comments; please let me
know if you think I'm missing something somewhere.
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 64d44c1ecad3..02ed01fa3499 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -95,6 +95,17 @@ htmldocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
+ifdef CONFIG_RUST
+htmlrust:
+ @make rustavailable
+ @make LLVM=1 rustdoc
+ @cp -r rust/doc/* Documentation/output/
+ @make htmldocs
+else
+htmlrust:
+ @echo "Error: CONFIG_RUST must be defined (see .config)"
+endif
First, if at all possible, the Rust documentation should just be built
along with the rest; no need for a separate make command. We don't have
separate build commands for any other subsystem's docs, and Rust should
be a first-class citizen here too.
Second, I'm not a big fan of that "cp" command, for a couple of reasons:
- It dumps a bunch of stuff into the main output directory, which risks
overwriting something someday. It seems like
Documentation/output/html/rust might be a better place.
- Rather than copying, I'd suggest changing the rustdoc command that
generates that output to just put it in the place where it should be.
Preferably it should work properly when people use separate build
trees as well.
It would also be nice to set up proper dependencies so that the Rust
docs are only regenerated if something has changed.
Does this all make sense? Sorry to come back with all this stuff...I
really do want to see this happen.
Thanks for your feedback, Jon and Miguel. Looks like you both agree on two
things: htmldocs should be the place to generate the extra Rust
documentation, and this should be done by making rustdoc use the proper
path directly (rather than by moving those contents). I will send a new
patch instead of v2, since it will be a whole other thing.
Thanks,
jon
Thanks,
Carlos
