Messages in this thread | | | Date | Wed, 30 Nov 2022 08:18:07 -0600 | Subject | Re: [PATCH] docs: Integrate rustdoc-generated output to Rust docs | From | Carlos Bilbao <> |
| |
On 11/28/22 16:23, Jonathan Corbet wrote:
> Carlos Bilbao <carlos.bilbao@amd.com> 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@amd.com> >> --- >> 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
| |