Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <e3523f33-847b-81da-7b20-83ee54597d9f@gmail.com>
Date:   Tue, 6 Dec 2022 22:32:42 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.4.2
From:   Akira Yokosawa <akiyks@gmail.com>
Subject: Re: [PATCH v2] docs: Integrate rustdoc into Rust documentation
To:     Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
Cc:     Carlos Bilbao <carlos.bilbao@amd.com>, ojeda@kernel.org,
        linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org,
        bilbao@vt.edu, corbet@lwn.net, konstantin@linuxfoundation.org,
        Akira Yokosawa <akiyks@gmail.com>
References: <20221130220825.1545758-1-carlos.bilbao@amd.com>
 <20221201204814.2141401-1-carlos.bilbao@amd.com>
 <a019a3f1-7ff1-15b2-d930-e1d722847e0c@gmail.com>
 <CANiq72=ud1EB+jcKE=iudFSgKNcqd=8Xe-M0YgxikmUuQ+TjGA@mail.gmail.com>
Content-Language: en-US
In-Reply-To: <CANiq72=ud1EB+jcKE=iudFSgKNcqd=8Xe-M0YgxikmUuQ+TjGA@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On Mon, 5 Dec 2022 17:08:53 +0100, Miguel Ojeda wrote:
> On Mon, Dec 5, 2022 at 2:06 AM Akira Yokosawa <akiyks@gmail.com> 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