diff mbox series

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

Message ID 20230717151624.3470714-2-carlos.bilbao@amd.com
State New
Headers
Series docs: Integrate rustdoc into Rust documentation |

Commit Message

Carlos Bilbao July 17, 2023, 3:16 p.m. UTC 
  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(-)

Comments

Miguel Ojeda July 17, 2023, 4:37 p.m. UTC | #1 
On Mon, Jul 17, 2023 at 5:16 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>
> +# Where to place rustdoc generated documentation
> +RUSTDOC_OUTPUT = $(objtree)/Documentation/output/rust/rustdoc

I think we may be able to get away with just `:=` instead of `=`.

Also, I assume this is intended to be overridable by the user, right?
i.e. that is why you wrote the identifier as uppercase.

In addition, I thought about basing it on `BUILDDIR` from the Doc's
`Makefile`, but that probably needs moving that one so that we can
access it here (in the case where we are not building as part of
`htmldocs`), and thus maybe it is not worth it.

(Cc'ing the rust-for-linux list, by the way)

Cheers,
Miguel
Carlos Bilbao July 18, 2023, 1:49 p.m. UTC | #2 
On 7/17/23 11:37, Miguel Ojeda wrote:
> On Mon, Jul 17, 2023 at 5:16 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>>
>> +# Where to place rustdoc generated documentation
>> +RUSTDOC_OUTPUT = $(objtree)/Documentation/output/rust/rustdoc
> 
> I think we may be able to get away with just `:=` instead of `=`.

Yes, for v8 we can simply use `:=`.

> 
> Also, I assume this is intended to be overridable by the user, right?
> i.e. that is why you wrote the identifier as uppercase.

That's true, I don't see any reason to make this uppercase.

> 
> In addition, I thought about basing it on `BUILDDIR` from the Doc's
> `Makefile`, but that probably needs moving that one so that we can
> access it here (in the case where we are not building as part of
> `htmldocs`), and thus maybe it is not worth it.
> 
> (Cc'ing the rust-for-linux list, by the way)

Thanks for CC'ing, I should have done it.

> 
> Cheers,
> Miguel

Thanks,
Carlos
Miguel Ojeda July 18, 2023, 3:24 p.m. UTC | #3 
On Tue, Jul 18, 2023 at 3:50 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>
> On 7/17/23 11:37, Miguel Ojeda wrote:
> >
> > Also, I assume this is intended to be overridable by the user, right?
> > i.e. that is why you wrote the identifier as uppercase.
>
> That's true, I don't see any reason to make this uppercase.

I don't know -- perhaps users may want to override the output
location. `BUILDDIR` is intended to be overridable, so we should
consider what should be the behavior when one overrides one but not
the other. Or perhaps this one shouldn't be overridable, like you did
in v8, in which case we should still make sure things work if that one
(`BUILDDIR`) is overridden.

Cheers,
Miguel
diff mbox series

Patch

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..3d502818e5d4 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,