Re: [PATCH] docs: Integrate rustdoc-generated output to Rust docs

[Carlos Bilbao]

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