[PATCH] docs: Integrate rustdoc into Rust documentation

From: Carlos Bilbao
Date: Wed Nov 30 2022 - 17:09:24 EST


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>
---
Documentation/Makefile | 4 ++++
Documentation/rust/index.rst | 1 +
Documentation/rust/rustdoc.rst | 7 +++++++
rust/Makefile | 15 +++++++++------
4 files changed, 21 insertions(+), 6 deletions(-)
create mode 100644 Documentation/rust/rustdoc.rst

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 64d44c1ecad3..5e9435198cfb 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
+ @make LLVM=1 rustdoc
+endif
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))

diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
index 4ae8c66b94fa..5e7a9d39af90 100644
--- a/Documentation/rust/index.rst
+++ b/Documentation/rust/index.rst
@@ -13,6 +13,7 @@ in the kernel, please read the quick-start.rst guide.
general-information
coding-guidelines
arch-support
+ rustdoc

.. only:: subproject and html

diff --git a/Documentation/rust/rustdoc.rst b/Documentation/rust/rustdoc.rst
new file mode 100644
index 000000000000..aa63a550b34c
--- /dev/null
+++ b/Documentation/rust/rustdoc.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Rustdoc output
+==============
+
+If this documentation includes rustdoc-generated HTML, the entry point
+can be found `here. <rustdoc/kernel/index.html>`_
diff --git a/rust/Makefile b/rust/Makefile
index f32df0e49815..eb2ff9260a6c 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

@@ -67,7 +70,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 $<

@@ -84,15 +87,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 \
@@ -153,7 +156,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-,,$@) $<

quiet_cmd_rustdoc_test_kernel = RUSTDOC TK $<
--
2.34.1