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

[Akira Yokosawa]

On Mon, 5 Dec 2022 17:08:53 +0100, Miguel Ojeda wrote:
> On Mon, Dec 5, 2022 at 2:06 AM Akira Yokosawa <akiyks@xxxxxxxxx> wrote:
>>
>> So, this means "make htmldocs" will require kernel .config if CONFIG_RUST=y.
>> I'm not sure this new requirement is acceptable for kernel documentation
>> testers who just want to build kernel documentation.
> 
> If the worry is that "full tree testers" (or CIs in general) cannot
> fully test the docs anymore without a config, that is definitely a
> change, and one of the reasons why I initially didn't add it to
> `htmldocs`.

Well, I'm actually worrying about additional TAT when I want to test
a particular change in a .rst file and test-build under the relevant
subdirectory using a command, e.g., "make SPHINXDIRS=doc-guide htmldocs".

This completes almost instantly when CONFIG_RUST is not set.

With CONFIG_RUST=y, in my test, it runs RUSTDOC even when rustdoc is
already generated once, as shown below:

------
  CALL    scripts/checksyscalls.sh
  DESCEND objtool
  RUSTDOC   /home/foo/.rustup/toolchains/1.62.0-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/lib.rs
  RUSTDOC H rust/macros/lib.rs
  RUSTDOC   rust/compiler_builtins.rs
  RUSTDOC   rust/alloc/lib.rs
  RUSTDOC   rust/kernel/lib.rs
  SPHINX  htmldocs --> file:///linux/Documentation/output/doc-guide
make[2]: Nothing to be done for 'html'.
Using classic theme
source directory: doc-guide
------

It takes 10 seconds or so (under a not-fast PC), 97% or more of which
is wasted for redundant RUSTDOC runs.

Why is RUSTDOC invoked when there is no change in rustdoc?

If those redundant runs can be resolved, I might change my mind and ack
the integration of generating rustdoc and htmldocs.

> 
> However, full tree testers will need other changes anyway (at least
> installing the Rust toolchain), even if there was no need for a
> config. So it may be not too bad, and putting it in `htmldocs` means
> not having to call another target in the CIs; and for humans, less
> chance of forgetting etc.

Full tree testers wouldn't mind the redundant runs of RUSTDOC.

I think you can add a new target in the top-devel Makefile which
runs both rustdoc and htmldocs for CIs. Something like 'htmldocsboth'
or 'htmldocsall'???

htmldocs and other *docs targets are the most primitive ones for
running Sphinx, so my gut feeling tells me _not_ to contaminate
htmldocs with rustdoc or vice versa.

> 
> (It is also why I wondered above about
> `CONFIG_WARN_MISSING_DOCUMENTS`: if `Documentation/` intended to
> require a config as a whole, then it would be fine. I assume that is
> not the case, though, but not doing the sync is nevertheless a bit
> confusing)

I have no idea. (Note: I was not around when the kernel documentation
transitioned to Sphinx.)

> 
>> By the way, is rustdoc's requirement of .config only for CONFIG_RUST?
>> In other words, are contents of rustdoc affected by other config settings?
>>
>> If not, I think rustdoc can be generated regardless of config settings as
>> far as necessary tools (rustc, bindgen, etc.) are available.
> 
> Yeah, at the moment the config affects what gets generated. However,
> that may change in the future: there has been some movement around the
> Rust features needed for this recently, so I want to try that approach
> again (it would require some other changes, though).

Interesting.
So rustdoc needs .config. I'm convinced.

        Thanks, Akira

> 
> Cheers,
> Miguel