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

[Carlos Bilbao <carlos.bilbao@amd.com>]

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