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;
From:   Jonathan Corbet <corbet@lwn.net>
To:     Carlos Bilbao <carlos.bilbao@amd.com>, ojeda@kernel.org
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        bilbao@vt.edu, Carlos Bilbao <carlos.bilbao@amd.com>
Subject: Re: [PATCH] docs: Integrate rustdoc-generated output to Rust docs
In-Reply-To: <20221128201932.168313-1-carlos.bilbao@amd.com>
References: <20221128201932.168313-1-carlos.bilbao@amd.com>
Date:   Mon, 28 Nov 2022 15:23:16 -0700
Message-ID: <87h6yi67mz.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

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,

jon