Re: [PATCH v7 1/2] docs: Move rustdoc output, cross-reference it

Re: [PATCH v7 1/2] docs: Move rustdoc output, cross-reference it

[Miguel Ojeda]

On Mon, Jul 17, 2023 at 5:16 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>
> +# Where to place rustdoc generated documentation
> +RUSTDOC_OUTPUT = $(objtree)/Documentation/output/rust/rustdoc

I think we may be able to get away with just `:=` instead of `=`.

Also, I assume this is intended to be overridable by the user, right?
i.e. that is why you wrote the identifier as uppercase.

In addition, I thought about basing it on `BUILDDIR` from the Doc's
`Makefile`, but that probably needs moving that one so that we can
access it here (in the case where we are not building as part of
`htmldocs`), and thus maybe it is not worth it.

(Cc'ing the rust-for-linux list, by the way)

Cheers,
Miguel

Re: [PATCH v7 1/2] docs: Move rustdoc output, cross-reference it

[Carlos Bilbao]

On 7/17/23 11:37, Miguel Ojeda wrote:
> On Mon, Jul 17, 2023 at 5:16 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>>
>> +# Where to place rustdoc generated documentation
>> +RUSTDOC_OUTPUT = $(objtree)/Documentation/output/rust/rustdoc
> 
> I think we may be able to get away with just `:=` instead of `=`.

Yes, for v8 we can simply use `:=`.

> 
> Also, I assume this is intended to be overridable by the user, right?
> i.e. that is why you wrote the identifier as uppercase.

That's true, I don't see any reason to make this uppercase.

> 
> In addition, I thought about basing it on `BUILDDIR` from the Doc's
> `Makefile`, but that probably needs moving that one so that we can
> access it here (in the case where we are not building as part of
> `htmldocs`), and thus maybe it is not worth it.
> 
> (Cc'ing the rust-for-linux list, by the way)

Thanks for CC'ing, I should have done it.

> 
> Cheers,
> Miguel

Thanks,
Carlos

Re: [PATCH v7 1/2] docs: Move rustdoc output, cross-reference it

[Miguel Ojeda]

On Tue, Jul 18, 2023 at 3:50 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>
> On 7/17/23 11:37, Miguel Ojeda wrote:
> >
> > Also, I assume this is intended to be overridable by the user, right?
> > i.e. that is why you wrote the identifier as uppercase.
>
> That's true, I don't see any reason to make this uppercase.

I don't know -- perhaps users may want to override the output
location. `BUILDDIR` is intended to be overridable, so we should
consider what should be the behavior when one overrides one but not
the other. Or perhaps this one shouldn't be overridable, like you did
in v8, in which case we should still make sure things work if that one
(`BUILDDIR`) is overridden.

Cheers,
Miguel

Re: [PATCH v7 2/2] docs: Integrate rustdoc generation into htmldocs

[Carlos Bilbao]

On 7/17/23 11:39, Miguel Ojeda wrote:
> On Mon, Jul 17, 2023 at 5:17 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>>
>> +       # Let Sphinx know we will include rustdoc
>> +       ALLSPHINXOPTS   +=  -t rustdoc
> 
> This is needed in the previous patch, no? I don't know if it fails or
> just does not work, but either way, perhaps you can split that from
> the first commit to put it last.

The previous patch works without this, the generated HTML will show in the
Rust index:

  This documentation does not include rustdoc generated information.

> 
>> +else
>> +       @echo "   Skipping Rust documentation since CONFIG_RUST is not y."
>> +endif
> 
> Is this printed for everybody? If so, then I think it is a good idea
> for the future, but perhaps a bit annoying right for most users right
> now.

Fair point, will remove as part of v8.

> 
> Cheers,
> Miguel

(CC'ed rust-for-linux list)


Thanks,
Carlos

Re: [PATCH v7 2/2] docs: Integrate rustdoc generation into htmldocs

[Miguel Ojeda]

On Tue, Jul 18, 2023 at 3:54 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>
> The previous patch works without this, the generated HTML will show in the
> Rust index:
>
>   This documentation does not include rustdoc generated information.

I see, thanks, then it does not matter much. I guess you put it in the
first commit because the docs were moved to the URL the docs talk
about, but it still means we are using a tag that does not yet exist,
so I would have put the "link/URL feature" as a separate commit
(together with the creation of the tag).

Cheers,
Miguel