Re: [PATCH] docs: Integrate rustdoc into Rust documentation

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

On 12/1/22 06:42, Miguel Ojeda wrote:

> On Wed, Nov 30, 2022 at 11:08 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>
>> +ifdef CONFIG_RUST
>> +       @make LLVM=1 rustdoc
>> +endif
> The Rust docs should probably be built with the build
> system/config/... as given, whether it is GCC, LLVM, etc. This should
> probably use `$(MAKE)` too; and if you intended to remove the command
> line definitions, `MAKEOVERRIDES` too.


Sounds good.


> By the way, while checking this, I noticed we use some `CONFIG_`s in
> this `Makefile`, but we do not perform a config sync for the `*docs`
> targets, so one needs to do so manually, i.e. it can be a pitfall for
> e.g. `CONFIG_WARN_MISSING_DOCUMENTS` and ` as well as a potential
> `CONFIG_RUST`. Should this be fixed orthogonally, or is it intended?
> (some targets do not need the sync, and the ones that need are
> probably less used, so I guess that could be the reason?).


I don't understand config sync. Perhaps that, e.g. Documentation/Makefile
checks for broken docs, for CONFIG_WARN_MISSING_DOCUMENTS, but we don't
do that for rust/Makefile? I'm not sure, but it does sound orthogonal, yes.


>
>> +Rustdoc output
>> +==============
>> +
>> +If this documentation includes rustdoc-generated HTML, the entry point
>> +can be found `here. <rustdoc/kernel/index.html>`_
> Perhaps this sentence could be moved to the top of the index file, so
> that users do not need two clicks when visiting "Rust"? That way we
> avoid one more file too.


Yes, that will be better :)


>
>> +RUSTDOC_OUTPUT=$(objtree)/Documentation/output/rust/rustdoc
> Please add a space around the equal sign to be consistent with (most)
> of the rest of the file.


Ack


>
> Cheers,
> Miguel


Thanks,
Carlos