[PATCH v8 0/2] docs: Integrate rustdoc into Rust documentation

[PATCH v8 0/2] docs: Integrate rustdoc into Rust documentation

[Carlos Bilbao]

Include HTML output generated with rustdoc into the Linux kernel
documentation on Rust.

Carlos Bilbao:
 docs: Move rustdoc output, cross-reference it
 docs: Integrate rustdoc generation into htmldocs

---
V7 is https://lore.kernel.org/lkml/20230717151624.3470714-1-carlos.bilbao@amd.com/T/#m5dcab9c7775e85331c0d067d411fe246ed39af1e
Changes since V7:
 - Use lowercase for rustdoc_output and define it with `:=`.
 - Remove messages that would be printed when skipping Rust documentation.

V6 is https://lore.kernel.org/lkml/20230127165728.119507-1-carl...
Changes since V6:
 - Skip Rust document generation entirely if .config doesn't exist.

Changes since V5:
 - Continue executing htmldocs even if rustdoc fails.

Changes since V4:
 - Limit rustdoc note only to html outputs.

Changes since V3:
 - Added Reviewed-Bys from Akira Yokosawa.
 - PATCH 1/2: Avoid error 404 adding tag `rustdoc` for Sphinx.
 - PATCH 1/2: Don't use "here" as link text, describe destination instead.
 - PATCH 2/2: Check CONFIG_RUST in a way that allows us to skip generation.
 - PATCH 2/2: Reoder Sphinx runs so they complete even if rustdoc fails.

Changes since V2:
 - Split v2 into two-patch series.
 - Add "only:: html" directive in Documentation/rust/index.rst reference

Changes since V1:
 - Work on top of v6.1-rc1.
 - 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       | 16 ++++++++++++++++
 Documentation/rust/index.rst |  8 ++++++++
 rust/Makefile                | 15 +++++++++------
 3 files changed, 33 insertions(+), 6 deletions(-)

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

[Carlos Bilbao]

Generate rustdoc documentation with the rest of subsystem's documentation
in Documentation/output. Add a cross reference to the generated rustdoc in
Documentation/rust/index.rst if Sphinx target rustdoc is set.

Reviewed-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
---
 Documentation/rust/index.rst |  8 ++++++++
 rust/Makefile                | 15 +++++++++------
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
index 4ae8c66b94fa..e599be2cec9b 100644
--- a/Documentation/rust/index.rst
+++ b/Documentation/rust/index.rst
@@ -6,6 +6,14 @@ Rust
 Documentation related to Rust within the kernel. To start using Rust
 in the kernel, please read the quick-start.rst guide.
 
+.. only:: rustdoc and html
+
+	You can also browse `rustdoc documentation <rustdoc/kernel/index.html>`_.
+
+.. only:: not rustdoc and html
+
+	This documentation does not include rustdoc generated information.
+
 .. toctree::
     :maxdepth: 1
 
diff --git a/rust/Makefile b/rust/Makefile
index 7c9d9f11aec5..dda1aecb8161 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
+
 obj-$(CONFIG_RUST) += core.o compiler_builtins.o
 always-$(CONFIG_RUST) += exports_core_generated.h
 
@@ -65,7 +68,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 $<
 
@@ -82,15 +85,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 \
@@ -154,7 +157,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,
-- 
2.34.1

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

[Carlos Bilbao]

Change target `make htmldocs` to combine RST Sphinx and the generation of
Rust documentation, when support is available and .config exists.

Reviewed-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
---
 Documentation/Makefile | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 023fa658a0a8..2f35793acd2a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -59,6 +59,12 @@ PAPEROPT_letter = -D latex_paper_size=letter
 KERNELDOC       = $(srctree)/scripts/kernel-doc
 KERNELDOC_CONF  = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
 ALLSPHINXOPTS   =  $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
+ifneq ($(wildcard $(srctree)/.config),)
+ifeq ($(CONFIG_RUST),y)
+	# Let Sphinx know we will include rustdoc
+	ALLSPHINXOPTS   +=  -t rustdoc
+endif
+endif
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
@@ -95,6 +101,16 @@ htmldocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
 	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
 
+# If Rust support is available and .config exists, add rustdoc generated contents.
+# If there are any, the errors from this make rustdoc will be displayed but
+# won't stop the execution of htmldocs
+
+ifneq ($(wildcard $(srctree)/.config),)
+ifeq ($(CONFIG_RUST),y)
+	$(Q)$(MAKE) rustdoc || true
+endif
+endif
+
 texinfodocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
 	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
-- 
2.34.1

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

[Martin Rodriguez Reboredo]

On 7/18/23 12:15, Carlos Bilbao wrote:
> Generate rustdoc documentation with the rest of subsystem's documentation
> in Documentation/output. Add a cross reference to the generated rustdoc in
> Documentation/rust/index.rst if Sphinx target rustdoc is set.
> 
> Reviewed-by: Akira Yokosawa <akiyks@gmail.com>
> Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
> ---
> [...]
Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>

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

[Martin Rodriguez Reboredo]

On 7/18/23 12:15, Carlos Bilbao wrote:
> Change target `make htmldocs` to combine RST Sphinx and the generation of
> Rust documentation, when support is available and .config exists.
> 
> Reviewed-by: Akira Yokosawa <akiyks@gmail.com>
> Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
> ---
> [...]
Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>

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

[Miguel Ojeda]

On Tue, Jul 18, 2023 at 5:15 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>
> Reviewed-by: Akira Yokosawa <akiyks@gmail.com>

Just in case: does this Reviewed-by still apply? (and the one in the
other commit)

> +.. only:: rustdoc and html
> +
> +       You can also browse `rustdoc documentation <rustdoc/kernel/index.html>`_.
> +
> +.. only:: not rustdoc and html
> +
> +       This documentation does not include rustdoc generated information.
> +

(I will move here a couple notes from v7 to avoid losing them, since
we were discussing there and then v8 was sent.)

I would move this to its own commit or to where the variable is
defined, but it is not critical since Carlos confirmed it does not
break the build.

> +# Where to place rustdoc generated documentation
> +rustdoc_output := $(objtree)/Documentation/output/rust/rustdoc

(From v7 too) Should this take into account `BUILDDIR`?

Cheers,
Miguel

Re: [PATCH v8 0/2] docs: Integrate rustdoc into Rust documentation

[Jonathan Corbet]

Carlos Bilbao <carlos.bilbao@amd.com> writes:

> Include HTML output generated with rustdoc into the Linux kernel
> documentation on Rust.
>
> Carlos Bilbao:
>  docs: Move rustdoc output, cross-reference it
>  docs: Integrate rustdoc generation into htmldocs

So I've been messing with this a bit, trying the various combinations.

- With no .config file, it behaves as it always did - thanks.

- With CONFIG_RUST=y I get the rustdocs, as expected.  There is a time
  penalty of about 5%, which is unfortunate, but that's the cost of
  progress, I guess.

- Setting CONFIG_RUST=n led to a crash with make complaining:
  "No rule to make target 'rustdoc'".  That isn't something I have been
  able to reproduce, though, so I have no idea what happened there; have
  you ever seen this?

Other than that one bit of strangeness, I think this is about ready to
be applied.

Thanks,

jon

Re: [PATCH v8 0/2] docs: Integrate rustdoc into Rust documentation

[Jonathan Corbet]

Jonathan Corbet <corbet@lwn.net> writes:

> Other than that one bit of strangeness, I think this is about ready to
> be applied.

...and I've just gone ahead and done that - thanks for doing this and
sticking with it!

jon

Re: [PATCH v8 0/2] docs: Integrate rustdoc into Rust documentation

[Carlos Bilbao]

On 7/20/23 17:46, Jonathan Corbet wrote:
> Carlos Bilbao <carlos.bilbao@amd.com> writes:
> 
>> Include HTML output generated with rustdoc into the Linux kernel
>> documentation on Rust.
>>
>> Carlos Bilbao:
>>   docs: Move rustdoc output, cross-reference it
>>   docs: Integrate rustdoc generation into htmldocs
> 
> So I've been messing with this a bit, trying the various combinations.
> 
> - With no .config file, it behaves as it always did - thanks.
> 
> - With CONFIG_RUST=y I get the rustdocs, as expected.  There is a time
>    penalty of about 5%, which is unfortunate, but that's the cost of
>    progress, I guess.
> 
> - Setting CONFIG_RUST=n led to a crash with make complaining:
>    "No rule to make target 'rustdoc'".  That isn't something I have been
>    able to reproduce, though, so I have no idea what happened there; have
>    you ever seen this?

I have not been able to reproduce this error either. If anyone comes across
this error in the future, please reach out to the list.

> 
> Other than that one bit of strangeness, I think this is about ready to
> be applied.
> 
> Thanks,
> 
> jon

Thanks,
Carlos