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

[Akira Yokosawa]

Hi,

On Thu, 1 Dec 2022 14:48:14 -0600, Carlos Bilbao wrote:
> Include HTML output generated with rustdoc into the Linux kernel
> documentation on Rust. Change target `make htmldocs` to combine RST Sphinx
> and the generation of Rust documentation, when support is available.
> 
> Signed-off-by: Carlos Bilbao <carlos.bilbao@xxxxxxx>
> ---
> 
> Changes since V1:
>  - Work on top of v6.1-rc1.

Thank you for the rebase.

>  - Don't use rustdoc.rst, instead add link to Documentation/rust/index.rst.
>  - In Documentation/Makefile, replace @make rustdoc for $(Q)$(MAKE) rustdoc.
>  - Don't do LLVM=1 for all rustdoc generation within `make htmldocs`.
>  - Add spaces on definition of RUSTDOC_OUTPUT, for consistency.
> 
> ---
>  Documentation/Makefile       |  4 ++++
>  Documentation/rust/index.rst |  3 +++
>  rust/Makefile                | 15 +++++++++------
>  3 files changed, 16 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 64d44c1ecad3..f537cf558af6 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -92,6 +92,10 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
>  	fi
>  
>  htmldocs:
> +# If Rust support is available, add rustdoc generated contents
> +ifdef CONFIG_RUST
> +	$(Q)$(MAKE) rustdoc
> +endif
>  	@$(srctree)/scripts/sphinx-pre-install --version-check
>  	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))

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.

You are doing three things in this patch.

 1) Change the destination of rustdoc to under Documentation/output/
 2) Add a cross reference to the generated rustdoc in
    Documentation/rust/index.rst.
 3) Integrate rustdoc generation into htmldocs.

I'm OK with 1) and 2).
Can you separate 3) into another patch and respin?

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.

>  
> diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
> index 4ae8c66b94fa..4005326c3ba9 100644
> --- a/Documentation/rust/index.rst
> +++ b/Documentation/rust/index.rst
> @@ -6,6 +6,9 @@ Rust
>  Documentation related to Rust within the kernel. To start using Rust
>  in the kernel, please read the quick-start.rst guide.
>  
> +If this documentation includes rustdoc-generated HTML, the entry point can
> +be found `here. <rustdoc/kernel/index.html>`_

This cross reference will only make sense in htmldocs build.
Perhaps, you can use the "only::" directive [1] as follows:

.. only:: html

    If this documentation includes rustdoc-generated HTML, the entry point can
    be found `here. <rustdoc/kernel/index.html>`_

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only

        Thanks, Akira

> +
>  .. toctree::
>      :maxdepth: 1
>  
> diff --git a/rust/Makefile b/rust/Makefile
> index 7700d3853404..080c07048065 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -1,5 +1,8 @@
>  # SPDX-License-Identifier: GPL-2.0
>  
> +# Where to place rustdoc generated documentation
> +RUSTDOC_OUTPUT = $(objtree)/Documentation/output/rust/rustdoc
> +
>  always-$(CONFIG_RUST) += target.json
>  no-clean-files += target.json
>  
> @@ -58,7 +61,7 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
>  	OBJTREE=$(abspath $(objtree)) \
>  	$(RUSTDOC) $(if $(rustdoc_host),$(rust_common_flags),$(rust_flags)) \
>  		$(rustc_target_flags) -L$(objtree)/$(obj) \
> -		--output $(objtree)/$(obj)/doc \
> +		--output $(RUSTDOC_OUTPUT) \
>  		--crate-name $(subst rustdoc-,,$@) \
>  		@$(objtree)/include/generated/rustc_cfg $<
>  
> @@ -75,15 +78,15 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
>  # and then retouch the generated files.
>  rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \
>      rustdoc-alloc rustdoc-kernel
> -	$(Q)cp $(srctree)/Documentation/images/logo.svg $(objtree)/$(obj)/doc
> -	$(Q)cp $(srctree)/Documentation/images/COPYING-logo $(objtree)/$(obj)/doc
> -	$(Q)find $(objtree)/$(obj)/doc -name '*.html' -type f -print0 | xargs -0 sed -Ei \
> +	$(Q)cp $(srctree)/Documentation/images/logo.svg $(RUSTDOC_OUTPUT)
> +	$(Q)cp $(srctree)/Documentation/images/COPYING-logo $(RUSTDOC_OUTPUT)
> +	$(Q)find $(RUSTDOC_OUTPUT) -name '*.html' -type f -print0 | xargs -0 sed -Ei \
>  		-e 's:rust-logo\.svg:logo.svg:g' \
>  		-e 's:rust-logo\.png:logo.svg:g' \
>  		-e 's:favicon\.svg:logo.svg:g' \
>  		-e 's:<link rel="alternate icon" type="image/png" href="[./]*favicon-(16x16|32x32)\.png">::g'
>  	$(Q)echo '.logo-container > img { object-fit: contain; }' \
> -		>> $(objtree)/$(obj)/doc/rustdoc.css
> +		>> $(RUSTDOC_OUTPUT)/rustdoc.css
>  
>  rustdoc-macros: private rustdoc_host = yes
>  rustdoc-macros: private rustc_target_flags = --crate-type proc-macro \
> @@ -141,7 +144,7 @@ quiet_cmd_rustdoc_test = RUSTDOC T $<
>  		@$(objtree)/include/generated/rustc_cfg \
>  		$(rustc_target_flags) $(rustdoc_test_target_flags) \
>  		--sysroot $(objtree)/$(obj)/test/sysroot $(rustdoc_test_quiet) \
> -		-L$(objtree)/$(obj)/test --output $(objtree)/$(obj)/doc \
> +		-L$(objtree)/$(obj)/test --output $(RUSTDOC_OUTPUT) \
>  		--crate-name $(subst rusttest-,,$@) $<
>  
>  # We cannot use `-Zpanic-abort-tests` because some tests are dynamic,
> 
> base-commit: 9abf2313adc1ca1b6180c508c25f22f9395cc780