lkml.org 
[lkml]   [2022]   [Nov]   [30]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
SubjectRe: [PATCH] docs: Integrate rustdoc-generated output to Rust docs
From
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

\
 
 \ /
  Last update: 2022-11-30 15:19    [W:0.453 / U:0.112 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site