* [PATCH] docs: Integrate rustdoc into Rust documentation @ 2022-11-30 22:08 Carlos Bilbao 2022-12-01 12:42 ` Miguel Ojeda 2022-12-01 20:48 ` [PATCH v2] " Carlos Bilbao 0 siblings, 2 replies; 26+ messages in thread From: Carlos Bilbao @ 2022-11-30 22:08 UTC (permalink / raw) To: corbet, ojeda; +Cc: bilbao, linux-doc, linux-kernel, konstantin, Carlos Bilbao 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@amd.com> --- 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 ^ permalink raw reply related [flat|nested] 26+ messages in thread
* Re: [PATCH] docs: Integrate rustdoc into Rust documentation 2022-11-30 22:08 [PATCH] docs: Integrate rustdoc into Rust documentation Carlos Bilbao @ 2022-12-01 12:42 ` Miguel Ojeda 2022-12-01 20:40 ` Carlos Bilbao 2022-12-01 20:48 ` [PATCH v2] " Carlos Bilbao 1 sibling, 1 reply; 26+ messages in thread From: Miguel Ojeda @ 2022-12-01 12:42 UTC (permalink / raw) To: Carlos Bilbao Cc: corbet, ojeda, bilbao, linux-doc, linux-kernel, konstantin, Akira Yokosawa On Wed, Nov 30, 2022 at 11:08 PM Carlos Bilbao <carlos.bilbao@amd.com> 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. Looks better, thanks for this v2! A few comments below... > +ifdef CONFIG_RUST > + @make LLVM=1 rustdoc > +endif The Rust docs should probably be built with the build system/config/... as given, whether it is GCC, LLVM, etc. This should probably use `$(MAKE)` too; and if you intended to remove the command line definitions, `MAKEOVERRIDES` too. Ideally `htmldocs` would depend on `rustdoc`, though that would require shuffling quite a few things since to build the Rust docs we need a subset of the Rust dependencies built. Given we may be changing things soon anyway on the Rust `Makefile`, we can leave that for the future. By the way, while checking this, I noticed we use some `CONFIG_`s in this `Makefile`, but we do not perform a config sync for the `*docs` targets, so one needs to do so manually, i.e. it can be a pitfall for e.g. `CONFIG_WARN_MISSING_DOCUMENTS` and ` as well as a potential `CONFIG_RUST`. Should this be fixed orthogonally, or is it intended? (some targets do not need the sync, and the ones that need are probably less used, so I guess that could be the reason?). > +Rustdoc output > +============== > + > +If this documentation includes rustdoc-generated HTML, the entry point > +can be found `here. <rustdoc/kernel/index.html>`_ Perhaps this sentence could be moved to the top of the index file, so that users do not need two clicks when visiting "Rust"? That way we avoid one more file too. > +RUSTDOC_OUTPUT=$(objtree)/Documentation/output/rust/rustdoc Please add a space around the equal sign to be consistent with (most) of the rest of the file. Cheers, Miguel ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH] docs: Integrate rustdoc into Rust documentation 2022-12-01 12:42 ` Miguel Ojeda @ 2022-12-01 20:40 ` Carlos Bilbao 2022-12-02 16:27 ` Miguel Ojeda 0 siblings, 1 reply; 26+ messages in thread From: Carlos Bilbao @ 2022-12-01 20:40 UTC (permalink / raw) To: Miguel Ojeda Cc: corbet, ojeda, bilbao, linux-doc, linux-kernel, konstantin, Akira Yokosawa On 12/1/22 06:42, Miguel Ojeda wrote: > On Wed, Nov 30, 2022 at 11:08 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote: > >> +ifdef CONFIG_RUST >> + @make LLVM=1 rustdoc >> +endif > The Rust docs should probably be built with the build > system/config/... as given, whether it is GCC, LLVM, etc. This should > probably use `$(MAKE)` too; and if you intended to remove the command > line definitions, `MAKEOVERRIDES` too. Sounds good. > By the way, while checking this, I noticed we use some `CONFIG_`s in > this `Makefile`, but we do not perform a config sync for the `*docs` > targets, so one needs to do so manually, i.e. it can be a pitfall for > e.g. `CONFIG_WARN_MISSING_DOCUMENTS` and ` as well as a potential > `CONFIG_RUST`. Should this be fixed orthogonally, or is it intended? > (some targets do not need the sync, and the ones that need are > probably less used, so I guess that could be the reason?). I don't understand config sync. Perhaps that, e.g. Documentation/Makefile checks for broken docs, for CONFIG_WARN_MISSING_DOCUMENTS, but we don't do that for rust/Makefile? I'm not sure, but it does sound orthogonal, yes. > >> +Rustdoc output >> +============== >> + >> +If this documentation includes rustdoc-generated HTML, the entry point >> +can be found `here. <rustdoc/kernel/index.html>`_ > Perhaps this sentence could be moved to the top of the index file, so > that users do not need two clicks when visiting "Rust"? That way we > avoid one more file too. Yes, that will be better :) > >> +RUSTDOC_OUTPUT=$(objtree)/Documentation/output/rust/rustdoc > Please add a space around the equal sign to be consistent with (most) > of the rest of the file. Ack > > Cheers, > Miguel Thanks, Carlos ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH] docs: Integrate rustdoc into Rust documentation 2022-12-01 20:40 ` Carlos Bilbao @ 2022-12-02 16:27 ` Miguel Ojeda 2022-12-02 16:30 ` Carlos Bilbao 0 siblings, 1 reply; 26+ messages in thread From: Miguel Ojeda @ 2022-12-02 16:27 UTC (permalink / raw) To: Carlos Bilbao Cc: corbet, ojeda, bilbao, linux-doc, linux-kernel, konstantin, Akira Yokosawa On Thu, Dec 1, 2022 at 9:40 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote: > > I don't understand config sync. Perhaps that, e.g. Documentation/Makefile > checks for broken docs, for CONFIG_WARN_MISSING_DOCUMENTS, but we don't > do that for rust/Makefile? I'm not sure, but it does sound orthogonal, yes. Config sync is what needs to happen to make a bunch of files in `include/` up to date with respect to the `.config`. It runs automatically for some targets, but not always. For instance, the `*docs` targets do not trigger it. So if you enable e.g. `CONFIG_WARN_MISSING_DOCUMENTS`, and immediately afterwards run `htmldocs`, it will not take it into account. But don't worry about it: that part of my comment was directed at others (e.g. Jon, Akira...) that may know the historical context or the reason behind it -- no need to fix it here. I mentioned it here since it affects `CONFIG_RUST` if we use it there (in the same way as the other `CONFIG_*` used there). Cheers, Miguel ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH] docs: Integrate rustdoc into Rust documentation 2022-12-02 16:27 ` Miguel Ojeda @ 2022-12-02 16:30 ` Carlos Bilbao 0 siblings, 0 replies; 26+ messages in thread From: Carlos Bilbao @ 2022-12-02 16:30 UTC (permalink / raw) To: Miguel Ojeda Cc: corbet, ojeda, bilbao, linux-doc, linux-kernel, konstantin, Akira Yokosawa On 12/2/22 10:27, Miguel Ojeda wrote: > On Thu, Dec 1, 2022 at 9:40 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote: >> I don't understand config sync. Perhaps that, e.g. Documentation/Makefile >> checks for broken docs, for CONFIG_WARN_MISSING_DOCUMENTS, but we don't >> do that for rust/Makefile? I'm not sure, but it does sound orthogonal, yes. > Config sync is what needs to happen to make a bunch of files in > `include/` up to date with respect to the `.config`. It runs > automatically for some targets, but not always. For instance, the > `*docs` targets do not trigger it. So if you enable e.g. > `CONFIG_WARN_MISSING_DOCUMENTS`, and immediately afterwards run > `htmldocs`, it will not take it into account. > > But don't worry about it: that part of my comment was directed at > others (e.g. Jon, Akira...) that may know the historical context or > the reason behind it -- no need to fix it here. I mentioned it here > since it affects `CONFIG_RUST` if we use it there (in the same way as > the other `CONFIG_*` used there). Ah, that makes sense. I appreciate the clarification! > > Cheers, > Miguel Thanks, Carlos ^ permalink raw reply [flat|nested] 26+ messages in thread
* [PATCH v2] docs: Integrate rustdoc into Rust documentation 2022-11-30 22:08 [PATCH] docs: Integrate rustdoc into Rust documentation Carlos Bilbao 2022-12-01 12:42 ` Miguel Ojeda @ 2022-12-01 20:48 ` Carlos Bilbao 2022-12-05 1:06 ` Akira Yokosawa 2022-12-06 15:31 ` [PATCH v3 0/2] " Carlos Bilbao 1 sibling, 2 replies; 26+ messages in thread From: Carlos Bilbao @ 2022-12-01 20:48 UTC (permalink / raw) To: corbet, ojeda, akiyks, konstantin Cc: linux-kernel, linux-doc, bilbao, Carlos Bilbao 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@amd.com> --- 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 | 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))) 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>`_ + .. 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 -- 2.34.1 ^ permalink raw reply related [flat|nested] 26+ messages in thread
* Re: [PATCH v2] docs: Integrate rustdoc into Rust documentation 2022-12-01 20:48 ` [PATCH v2] " Carlos Bilbao @ 2022-12-05 1:06 ` Akira Yokosawa 2022-12-05 16:08 ` Miguel Ojeda 2022-12-05 16:36 ` Carlos Bilbao 2022-12-06 15:31 ` [PATCH v3 0/2] " Carlos Bilbao 1 sibling, 2 replies; 26+ messages in thread From: Akira Yokosawa @ 2022-12-05 1:06 UTC (permalink / raw) To: Carlos Bilbao, ojeda Cc: linux-kernel, linux-doc, bilbao, corbet, konstantin, 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@amd.com> > --- > > 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 ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v2] docs: Integrate rustdoc into Rust documentation 2022-12-05 1:06 ` Akira Yokosawa @ 2022-12-05 16:08 ` Miguel Ojeda 2022-12-06 13:32 ` Akira Yokosawa 2022-12-05 16:36 ` Carlos Bilbao 1 sibling, 1 reply; 26+ messages in thread From: Miguel Ojeda @ 2022-12-05 16:08 UTC (permalink / raw) To: Akira Yokosawa Cc: Carlos Bilbao, ojeda, linux-kernel, linux-doc, bilbao, corbet, konstantin On Mon, Dec 5, 2022 at 2:06 AM Akira Yokosawa <akiyks@gmail.com> wrote: > > 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. If the worry is that "full tree testers" (or CIs in general) cannot fully test the docs anymore without a config, that is definitely a change, and one of the reasons why I initially didn't add it to `htmldocs`. However, full tree testers will need other changes anyway (at least installing the Rust toolchain), even if there was no need for a config. So it may be not too bad, and putting it in `htmldocs` means not having to call another target in the CIs; and for humans, less chance of forgetting etc. (It is also why I wondered above about `CONFIG_WARN_MISSING_DOCUMENTS`: if `Documentation/` intended to require a config as a whole, then it would be fine. I assume that is not the case, though, but not doing the sync is nevertheless a bit confusing) > 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. Yeah, at the moment the config affects what gets generated. However, that may change in the future: there has been some movement around the Rust features needed for this recently, so I want to try that approach again (it would require some other changes, though). Cheers, Miguel ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v2] docs: Integrate rustdoc into Rust documentation 2022-12-05 16:08 ` Miguel Ojeda @ 2022-12-06 13:32 ` Akira Yokosawa 2022-12-06 15:02 ` Jonathan Corbet 2022-12-06 15:39 ` Miguel Ojeda 0 siblings, 2 replies; 26+ messages in thread From: Akira Yokosawa @ 2022-12-06 13:32 UTC (permalink / raw) To: Miguel Ojeda Cc: Carlos Bilbao, ojeda, linux-kernel, linux-doc, bilbao, corbet, konstantin, Akira Yokosawa On Mon, 5 Dec 2022 17:08:53 +0100, Miguel Ojeda wrote: > On Mon, Dec 5, 2022 at 2:06 AM Akira Yokosawa <akiyks@gmail.com> wrote: >> >> 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. > > If the worry is that "full tree testers" (or CIs in general) cannot > fully test the docs anymore without a config, that is definitely a > change, and one of the reasons why I initially didn't add it to > `htmldocs`. Well, I'm actually worrying about additional TAT when I want to test a particular change in a .rst file and test-build under the relevant subdirectory using a command, e.g., "make SPHINXDIRS=doc-guide htmldocs". This completes almost instantly when CONFIG_RUST is not set. With CONFIG_RUST=y, in my test, it runs RUSTDOC even when rustdoc is already generated once, as shown below: ------ CALL scripts/checksyscalls.sh DESCEND objtool RUSTDOC /home/foo/.rustup/toolchains/1.62.0-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/lib.rs RUSTDOC H rust/macros/lib.rs RUSTDOC rust/compiler_builtins.rs RUSTDOC rust/alloc/lib.rs RUSTDOC rust/kernel/lib.rs SPHINX htmldocs --> file:///linux/Documentation/output/doc-guide make[2]: Nothing to be done for 'html'. Using classic theme source directory: doc-guide ------ It takes 10 seconds or so (under a not-fast PC), 97% or more of which is wasted for redundant RUSTDOC runs. Why is RUSTDOC invoked when there is no change in rustdoc? If those redundant runs can be resolved, I might change my mind and ack the integration of generating rustdoc and htmldocs. > > However, full tree testers will need other changes anyway (at least > installing the Rust toolchain), even if there was no need for a > config. So it may be not too bad, and putting it in `htmldocs` means > not having to call another target in the CIs; and for humans, less > chance of forgetting etc. Full tree testers wouldn't mind the redundant runs of RUSTDOC. I think you can add a new target in the top-devel Makefile which runs both rustdoc and htmldocs for CIs. Something like 'htmldocsboth' or 'htmldocsall'??? htmldocs and other *docs targets are the most primitive ones for running Sphinx, so my gut feeling tells me _not_ to contaminate htmldocs with rustdoc or vice versa. > > (It is also why I wondered above about > `CONFIG_WARN_MISSING_DOCUMENTS`: if `Documentation/` intended to > require a config as a whole, then it would be fine. I assume that is > not the case, though, but not doing the sync is nevertheless a bit > confusing) I have no idea. (Note: I was not around when the kernel documentation transitioned to Sphinx.) > >> 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. > > Yeah, at the moment the config affects what gets generated. However, > that may change in the future: there has been some movement around the > Rust features needed for this recently, so I want to try that approach > again (it would require some other changes, though). Interesting. So rustdoc needs .config. I'm convinced. Thanks, Akira > > Cheers, > Miguel ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v2] docs: Integrate rustdoc into Rust documentation 2022-12-06 13:32 ` Akira Yokosawa @ 2022-12-06 15:02 ` Jonathan Corbet 2022-12-06 15:39 ` Miguel Ojeda 1 sibling, 0 replies; 26+ messages in thread From: Jonathan Corbet @ 2022-12-06 15:02 UTC (permalink / raw) To: Akira Yokosawa, Miguel Ojeda Cc: Carlos Bilbao, ojeda, linux-kernel, linux-doc, bilbao, konstantin, Akira Yokosawa Akira Yokosawa <akiyks@gmail.com> writes: > Well, I'm actually worrying about additional TAT when I want to test > a particular change in a .rst file and test-build under the relevant > subdirectory using a command, e.g., "make SPHINXDIRS=doc-guide htmldocs". > > This completes almost instantly when CONFIG_RUST is not set. > > With CONFIG_RUST=y, in my test, it runs RUSTDOC even when rustdoc is > already generated once, as shown below: This is something that would be nice to avoid if we can; narrowing things with SPHINXDIRS should avoid building anything that the user isn't asking for. I'm not sure how much makefile pain would be required to make that happen...Documentation/Makefile is not the easiest place to make changes, alas. > I think you can add a new target in the top-devel Makefile which > runs both rustdoc and htmldocs for CIs. Something like 'htmldocsboth' > or 'htmldocsall'??? > > htmldocs and other *docs targets are the most primitive ones for > running Sphinx, so my gut feeling tells me _not_ to contaminate > htmldocs with rustdoc or vice versa. Well, I *would* like for a bare "make htmldocs" to make *all* of the docs; I don't think Rust should be special in that regard. >> (It is also why I wondered above about >> `CONFIG_WARN_MISSING_DOCUMENTS`: if `Documentation/` intended to >> require a config as a whole, then it would be fine. I assume that is >> not the case, though, but not doing the sync is nevertheless a bit >> confusing) > > I have no idea. (Note: I was not around when the kernel documentation > transitioned to Sphinx.) I think we're just seeing the implementation as was rammed in by somebody in a hurry; I don't doubt it could be improved. Thanks, jon (currently traveling and scrambling to get ready for the merge window) ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v2] docs: Integrate rustdoc into Rust documentation 2022-12-06 13:32 ` Akira Yokosawa 2022-12-06 15:02 ` Jonathan Corbet @ 2022-12-06 15:39 ` Miguel Ojeda 1 sibling, 0 replies; 26+ messages in thread From: Miguel Ojeda @ 2022-12-06 15:39 UTC (permalink / raw) To: Akira Yokosawa Cc: Carlos Bilbao, ojeda, linux-kernel, linux-doc, bilbao, corbet, konstantin On Tue, Dec 6, 2022 at 2:32 PM Akira Yokosawa <akiyks@gmail.com> wrote: > > Why is RUSTDOC invoked when there is no change in rustdoc? I think we can give proper dependencies to `rustdoc`, so if that is the main concern, then it should be OK. But note that `htmldocs` also calls Sphinx every run. It does a subset of the work, but perhaps we can save some time there if we could detect whether anything changed. > I think you can add a new target in the top-devel Makefile which > runs both rustdoc and htmldocs for CIs. Something like 'htmldocsboth' > or 'htmldocsall'??? > > htmldocs and other *docs targets are the most primitive ones for > running Sphinx, so my gut feeling tells me _not_ to contaminate > htmldocs with rustdoc or vice versa. That is reasonable, but others wanted it in `htmldocs` (and the goal is to eventually do so, so if we can do it already, even better). Cheers, Miguel ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v2] docs: Integrate rustdoc into Rust documentation 2022-12-05 1:06 ` Akira Yokosawa 2022-12-05 16:08 ` Miguel Ojeda @ 2022-12-05 16:36 ` Carlos Bilbao 2022-12-06 14:22 ` Akira Yokosawa 1 sibling, 1 reply; 26+ messages in thread From: Carlos Bilbao @ 2022-12-05 16:36 UTC (permalink / raw) To: Akira Yokosawa, ojeda; +Cc: linux-kernel, linux-doc, bilbao, corbet, konstantin On 12/4/22 19:06, Akira Yokosawa wrote: > 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@amd.com> >> --- >> >> 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. This is already kind of the case for Rust-related business. > > 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? Glad we can agree on 1) and 2). Why moving 3)? This is a small patch with one overall purpose (Integrate rustdoc into website). > > 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. Yes, but someone with the tools may not want to use them. Keep in mind that generating rustdoc takes a few extra seconds. > >> >> 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 This I can gladly do on a V3. I will wait for an answer on issues above. > > If this documentation includes rustdoc-generated HTML, the entry point can > be found `here. <rustdoc/kernel/index.html>`_ > > [1]: https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.sphinx-doc.org%2Fen%2Fmaster%2Fusage%2Frestructuredtext%2Fdirectives.html%23directive-only&data=05%7C01%7Ccarlos.bilbao%40amd.com%7C163763a795284a542e4f08dad65cf4c6%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C638057991984040258%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=DU8nmQp7gCCGNMUR6urtHHCz5nXAtomeV17%2BzB%2F4L38%3D&reserved=0 > > 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 Thanks, Carlos ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v2] docs: Integrate rustdoc into Rust documentation 2022-12-05 16:36 ` Carlos Bilbao @ 2022-12-06 14:22 ` Akira Yokosawa 2022-12-06 14:55 ` Carlos Bilbao 2022-12-06 15:01 ` Carlos Bilbao 0 siblings, 2 replies; 26+ messages in thread From: Akira Yokosawa @ 2022-12-06 14:22 UTC (permalink / raw) To: Carlos Bilbao Cc: linux-kernel, linux-doc, bilbao, corbet, konstantin, ojeda, Akira Yokosawa On Mon, 5 Dec 2022 10:36:11 -0600, Carlos Bilbao wrote: > On 12/4/22 19:06, Akira Yokosawa wrote: > >> 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@amd.com> >>> --- >>> >>> 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. > > > This is already kind of the case for Rust-related business. > > >> >> 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? > > > Glad we can agree on 1) and 2). Why moving 3)? This is a small patch with > one overall purpose (Integrate rustdoc into website). Yes, I agree that 3) is a small change. I understand what you want to do. But there are a couple of options for _how_ to do it. My current position is that Documentation/Makefile is _not_ the right place for the change, as mentioned in my reply to Miguel. > > >> >> 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. > > > Yes, but someone with the tools may not want to use them. Keep in mind that > generating rustdoc takes a few extra seconds. As mentioned in another reply, I'm convinced of the dependency on .config. > > >> >>> 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 > > > This I can gladly do on a V3. I will wait for an answer on issues above. OK. So if you split this into a two-patch series, 1/2 for 1) and 2), and 2/2 for 3) (or an updated one), I'm glad to give my RB tag to 1/2 for Miguel to be able take it for v6.2 (timing is tight!). 2/2 will need at least a couple of respins, I guess. Thanks, Akira > > >> >> If this documentation includes rustdoc-generated HTML, the entry point can >> be found `here. <rustdoc/kernel/index.html>`_ >> >> [1]: https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.sphinx-doc.org%2Fen%2Fmaster%2Fusage%2Frestructuredtext%2Fdirectives.html%23directive-only&data=05%7C01%7Ccarlos.bilbao%40amd.com%7C163763a795284a542e4f08dad65cf4c6%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C638057991984040258%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=DU8nmQp7gCCGNMUR6urtHHCz5nXAtomeV17%2BzB%2F4L38%3D&reserved=0 >> >> 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 > > > Thanks, > Carlos ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v2] docs: Integrate rustdoc into Rust documentation 2022-12-06 14:22 ` Akira Yokosawa @ 2022-12-06 14:55 ` Carlos Bilbao 2022-12-06 15:01 ` Carlos Bilbao 1 sibling, 0 replies; 26+ messages in thread From: Carlos Bilbao @ 2022-12-06 14:55 UTC (permalink / raw) To: Akira Yokosawa; +Cc: linux-kernel, linux-doc, bilbao, corbet, konstantin, ojeda On 12/6/22 08:22, Akira Yokosawa wrote: > On Mon, 5 Dec 2022 10:36:11 -0600, Carlos Bilbao wrote: >> On 12/4/22 19:06, Akira Yokosawa wrote: >> >>> 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@amd.com> >>>> --- >>>> >>>> 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. >> >> This is already kind of the case for Rust-related business. >> >> >>> 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? >> >> Glad we can agree on 1) and 2). Why moving 3)? This is a small patch with >> one overall purpose (Integrate rustdoc into website). > Yes, I agree that 3) is a small change. I understand what you want to > do. But there are a couple of options for _how_ to do it. > My current position is that Documentation/Makefile is _not_ the right > place for the change, as mentioned in my reply to Miguel. > >> >>> 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. >> >> Yes, but someone with the tools may not want to use them. Keep in mind that >> generating rustdoc takes a few extra seconds. > As mentioned in another reply, I'm convinced of the dependency on .config. > >> >>>> 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 >> >> This I can gladly do on a V3. I will wait for an answer on issues above. > OK. > > So if you split this into a two-patch series, 1/2 for 1) and 2), and 2/2 > for 3) (or an updated one), I'm glad to give my RB tag to 1/2 for Miguel > to be able take it for v6.2 (timing is tight!). 2/2 will need at least > a couple of respins, I guess. Sounds good, I will divide for v3. > > Thanks, Akira >> >>> If this documentation includes rustdoc-generated HTML, the entry point can >>> be found `here. <rustdoc/kernel/index.html>`_ >>> >>> [1]: https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.sphinx-doc.org%2Fen%2Fmaster%2Fusage%2Frestructuredtext%2Fdirectives.html%23directive-only&data=05%7C01%7Ccarlos.bilbao%40amd.com%7Cbed091b8fae74b3d314408dad7954fc2%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C638059333550278394%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=xGbmhYsge%2BoPo%2BRrsc6fCW8htY3yh0dHk4E8gQBQV9o%3D&reserved=0 >>> >>> 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 >> >> Thanks, >> Carlos ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v2] docs: Integrate rustdoc into Rust documentation 2022-12-06 14:22 ` Akira Yokosawa 2022-12-06 14:55 ` Carlos Bilbao @ 2022-12-06 15:01 ` Carlos Bilbao 1 sibling, 0 replies; 26+ messages in thread From: Carlos Bilbao @ 2022-12-06 15:01 UTC (permalink / raw) To: Akira Yokosawa; +Cc: linux-kernel, linux-doc, bilbao, corbet, konstantin, ojeda On 12/6/22 08:22, Akira Yokosawa wrote: > On Mon, 5 Dec 2022 10:36:11 -0600, Carlos Bilbao wrote: >> On 12/4/22 19:06, Akira Yokosawa wrote: >> >>> 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@amd.com> >>>> --- >>>> >>>> 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. >> >> This is already kind of the case for Rust-related business. >> >> >>> 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? >> >> Glad we can agree on 1) and 2). Why moving 3)? This is a small patch with >> one overall purpose (Integrate rustdoc into website). > Yes, I agree that 3) is a small change. I understand what you want to > do. But there are a couple of options for _how_ to do it. > My current position is that Documentation/Makefile is _not_ the right > place for the change, as mentioned in my reply to Miguel. Actually, I originally used `make rustdocs` [1] but good arguments were given to use `make htmldocs` instead, and I was convinced too. > >> >>> 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. >> >> Yes, but someone with the tools may not want to use them. Keep in mind that >> generating rustdoc takes a few extra seconds. > As mentioned in another reply, I'm convinced of the dependency on .config. > >> >>>> 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 >> >> This I can gladly do on a V3. I will wait for an answer on issues above. > OK. > > So if you split this into a two-patch series, 1/2 for 1) and 2), and 2/2 > for 3) (or an updated one), I'm glad to give my RB tag to 1/2 for Miguel > to be able take it for v6.2 (timing is tight!). 2/2 will need at least > a couple of respins, I guess. Sounds good, I will divide for v3. > > Thanks, Akira >> >>> If this documentation includes rustdoc-generated HTML, the entry point can >>> be found `here. <rustdoc/kernel/index.html>`_ >>> >>> [1]: https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.sphinx-doc.org%2Fen%2Fmaster%2Fusage%2Frestructuredtext%2Fdirectives.html%23directive-only&data=05%7C01%7Ccarlos.bilbao%40amd.com%7Cbed091b8fae74b3d314408dad7954fc2%7C3dd8961fe4884e608e11a82d994e183d%7C0%7C0%7C638059333550278394%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=xGbmhYsge%2BoPo%2BRrsc6fCW8htY3yh0dHk4E8gQBQV9o%3D&reserved=0 >>> >>> 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 >> >> Thanks, >> Carlos [1] https://lore.kernel.org/lkml/a019a3f1-7ff1-15b2-d930-e1d722847e0c@gmail.com/T/ Thanks, Carlos ^ permalink raw reply [flat|nested] 26+ messages in thread
* [PATCH v3 0/2] docs: Integrate rustdoc into Rust documentation 2022-12-01 20:48 ` [PATCH v2] " Carlos Bilbao 2022-12-05 1:06 ` Akira Yokosawa @ 2022-12-06 15:31 ` Carlos Bilbao 2022-12-06 15:31 ` [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it Carlos Bilbao 2022-12-06 15:31 ` [PATCH v3 2/2] docs: Integrate rustdoc generation into htmldocs Carlos Bilbao 1 sibling, 2 replies; 26+ messages in thread From: Carlos Bilbao @ 2022-12-06 15:31 UTC (permalink / raw) To: corbet, akiyks, ojeda Cc: linux-doc, linux-kernel, bilbao, konstantin, 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 --- 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 | 4 ++++ Documentation/rust/index.rst | 5 +++++ rust/Makefile | 15 +++++++++------ 3 files changed, 18 insertions(+), 6 deletions(-) ^ permalink raw reply [flat|nested] 26+ messages in thread
* [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it 2022-12-06 15:31 ` [PATCH v3 0/2] " Carlos Bilbao @ 2022-12-06 15:31 ` Carlos Bilbao 2022-12-06 22:56 ` Akira Yokosawa 2022-12-07 8:27 ` Jani Nikula 2022-12-06 15:31 ` [PATCH v3 2/2] docs: Integrate rustdoc generation into htmldocs Carlos Bilbao 1 sibling, 2 replies; 26+ messages in thread From: Carlos Bilbao @ 2022-12-06 15:31 UTC (permalink / raw) To: corbet, akiyks, ojeda Cc: linux-doc, linux-kernel, bilbao, konstantin, 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. Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com> --- Documentation/rust/index.rst | 5 +++++ rust/Makefile | 15 +++++++++------ 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst index 4ae8c66b94fa..416d6b3de1e4 100644 --- a/Documentation/rust/index.rst +++ b/Documentation/rust/index.rst @@ -6,6 +6,11 @@ Rust Documentation related to Rust within the kernel. To start using Rust in the kernel, please read the quick-start.rst guide. +.. only:: html + + If this documentation includes rustdoc-generated HTML, the entry + point can be found `here <rustdoc/kernel/index.html>`_. + .. 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, -- 2.34.1 ^ permalink raw reply related [flat|nested] 26+ messages in thread
* Re: [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it 2022-12-06 15:31 ` [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it Carlos Bilbao @ 2022-12-06 22:56 ` Akira Yokosawa 2022-12-07 8:27 ` Jani Nikula 1 sibling, 0 replies; 26+ messages in thread From: Akira Yokosawa @ 2022-12-06 22:56 UTC (permalink / raw) To: Carlos Bilbao, corbet, ojeda Cc: linux-doc, linux-kernel, bilbao, konstantin, Akira Yokosawa On Tue, 6 Dec 2022 09:31:50 -0600, 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. > > Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com> Reviewed-by: Akira Yokosawa <akiyks@gmail.com> > --- > Documentation/rust/index.rst | 5 +++++ > rust/Makefile | 15 +++++++++------ > 2 files changed, 14 insertions(+), 6 deletions(-) > > diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst > index 4ae8c66b94fa..416d6b3de1e4 100644 > --- a/Documentation/rust/index.rst > +++ b/Documentation/rust/index.rst > @@ -6,6 +6,11 @@ Rust > Documentation related to Rust within the kernel. To start using Rust > in the kernel, please read the quick-start.rst guide. > > +.. only:: html > + > + If this documentation includes rustdoc-generated HTML, the entry > + point can be found `here <rustdoc/kernel/index.html>`_. > + > .. 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, ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it 2022-12-06 15:31 ` [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it Carlos Bilbao 2022-12-06 22:56 ` Akira Yokosawa @ 2022-12-07 8:27 ` Jani Nikula 2022-12-07 13:49 ` Carlos Bilbao 1 sibling, 1 reply; 26+ messages in thread From: Jani Nikula @ 2022-12-07 8:27 UTC (permalink / raw) To: Carlos Bilbao, corbet, akiyks, ojeda Cc: linux-doc, linux-kernel, bilbao, konstantin, Carlos Bilbao On Tue, 06 Dec 2022, Carlos Bilbao <carlos.bilbao@amd.com> 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. > > Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com> > --- > Documentation/rust/index.rst | 5 +++++ > rust/Makefile | 15 +++++++++------ > 2 files changed, 14 insertions(+), 6 deletions(-) > > diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst > index 4ae8c66b94fa..416d6b3de1e4 100644 > --- a/Documentation/rust/index.rst > +++ b/Documentation/rust/index.rst > @@ -6,6 +6,11 @@ Rust > Documentation related to Rust within the kernel. To start using Rust > in the kernel, please read the quick-start.rst guide. > > +.. only:: html > + > + If this documentation includes rustdoc-generated HTML, the entry > + point can be found `here <rustdoc/kernel/index.html>`_. > + It's a bit meh to have documentation that points to places that might 404 and the user has to figure it out. We can do better than that. You could use CONFIG_RUST to pass e.g. "-t rustdoc" to Sphinx in the Makefile, and use: .. only:: rustdoc and .. only:: not rustdoc And document accordingly. Also, please don't use "here" as the link text. BR, Jani. > .. 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, -- Jani Nikula, Intel Open Source Graphics Center ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it 2022-12-07 8:27 ` Jani Nikula @ 2022-12-07 13:49 ` Carlos Bilbao 2022-12-07 14:15 ` Jani Nikula 2022-12-07 19:33 ` Jonathan Corbet 0 siblings, 2 replies; 26+ messages in thread From: Carlos Bilbao @ 2022-12-07 13:49 UTC (permalink / raw) To: Jani Nikula, corbet, akiyks, ojeda Cc: linux-doc, linux-kernel, bilbao, konstantin On 12/7/22 2:27 AM, Jani Nikula wrote: > On Tue, 06 Dec 2022, Carlos Bilbao <carlos.bilbao@amd.com> 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. >> >> Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com> >> --- >> Documentation/rust/index.rst | 5 +++++ >> rust/Makefile | 15 +++++++++------ >> 2 files changed, 14 insertions(+), 6 deletions(-) >> >> diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst >> index 4ae8c66b94fa..416d6b3de1e4 100644 >> --- a/Documentation/rust/index.rst >> +++ b/Documentation/rust/index.rst >> @@ -6,6 +6,11 @@ Rust >> Documentation related to Rust within the kernel. To start using Rust >> in the kernel, please read the quick-start.rst guide. >> >> +.. only:: html >> + >> + If this documentation includes rustdoc-generated HTML, the entry >> + point can be found `here <rustdoc/kernel/index.html>`_. >> + > > It's a bit meh to have documentation that points to places that might > 404 and the user has to figure it out. > > We can do better than that. > > You could use CONFIG_RUST to pass e.g. "-t rustdoc" to Sphinx in the > Makefile, and use: > > .. only:: rustdoc > > and > > .. only:: not rustdoc > > And document accordingly. > > Also, please don't use "here" as the link text. Why not? > > BR, > Jani. > > >> .. 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, > Thanks, Carlos ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it 2022-12-07 13:49 ` Carlos Bilbao @ 2022-12-07 14:15 ` Jani Nikula 2022-12-07 15:06 ` Carlos Bilbao 2022-12-07 19:33 ` Jonathan Corbet 1 sibling, 1 reply; 26+ messages in thread From: Jani Nikula @ 2022-12-07 14:15 UTC (permalink / raw) To: Carlos Bilbao, corbet, akiyks, ojeda Cc: linux-doc, linux-kernel, bilbao, konstantin On Wed, 07 Dec 2022, Carlos Bilbao <carlos.bilbao@amd.com> wrote: > On 12/7/22 2:27 AM, Jani Nikula wrote: >> Also, please don't use "here" as the link text. > > Why not? It's considered bad style, see e.g. [1] or [2] or the plethora of results you get if you search for "here as the link text". The link text should describe what's at the destination. BR, Jani. [1] https://ux.stackexchange.com/questions/12100/why-shouldnt-we-use-words-such-as-here-and-this-in-textlinks [2] https://www.w3.org/QA/Tips/noClickHere -- Jani Nikula, Intel Open Source Graphics Center ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it 2022-12-07 14:15 ` Jani Nikula @ 2022-12-07 15:06 ` Carlos Bilbao 0 siblings, 0 replies; 26+ messages in thread From: Carlos Bilbao @ 2022-12-07 15:06 UTC (permalink / raw) To: Jani Nikula, corbet, akiyks, ojeda Cc: linux-doc, linux-kernel, bilbao, konstantin On 12/7/22 08:15, Jani Nikula wrote: > On Wed, 07 Dec 2022, Carlos Bilbao <carlos.bilbao@amd.com> wrote: >> On 12/7/22 2:27 AM, Jani Nikula wrote: >>> Also, please don't use "here" as the link text. >> Why not? > It's considered bad style, see e.g. [1] or [2] or the plethora of > results you get if you search for "here as the link text". > > The link text should describe what's at the destination. Understood, thanks! > > BR, > Jani. > > > [1] https://ux.stackexchange.com/questions/12100/why-shouldnt-we-use-words-such-as-here-and-this-in-textlinks > [2] https://www.w3.org/QA/Tips/noClickHere > > Best regards, Carlos ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it 2022-12-07 13:49 ` Carlos Bilbao 2022-12-07 14:15 ` Jani Nikula @ 2022-12-07 19:33 ` Jonathan Corbet 1 sibling, 0 replies; 26+ messages in thread From: Jonathan Corbet @ 2022-12-07 19:33 UTC (permalink / raw) To: Carlos Bilbao, Jani Nikula, akiyks, ojeda Cc: linux-doc, linux-kernel, bilbao, konstantin Carlos Bilbao <carlos.bilbao@amd.com> writes: > On 12/7/22 2:27 AM, Jani Nikula wrote: >> Also, please don't use "here" as the link text. > > Why not? Among other things, that makes things harder for people using screen readers and other assistive technology. Thanks, jon ^ permalink raw reply [flat|nested] 26+ messages in thread
* [PATCH v3 2/2] docs: Integrate rustdoc generation into htmldocs 2022-12-06 15:31 ` [PATCH v3 0/2] " Carlos Bilbao 2022-12-06 15:31 ` [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it Carlos Bilbao @ 2022-12-06 15:31 ` Carlos Bilbao 2022-12-06 23:11 ` Akira Yokosawa 1 sibling, 1 reply; 26+ messages in thread From: Carlos Bilbao @ 2022-12-06 15:31 UTC (permalink / raw) To: corbet, akiyks, ojeda Cc: linux-doc, linux-kernel, bilbao, konstantin, Carlos Bilbao 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@amd.com> --- Documentation/Makefile | 4 ++++ 1 file changed, 4 insertions(+) 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))) -- 2.34.1 ^ permalink raw reply related [flat|nested] 26+ messages in thread
* Re: [PATCH v3 2/2] docs: Integrate rustdoc generation into htmldocs 2022-12-06 15:31 ` [PATCH v3 2/2] docs: Integrate rustdoc generation into htmldocs Carlos Bilbao @ 2022-12-06 23:11 ` Akira Yokosawa 2022-12-07 0:06 ` Randy Dunlap 0 siblings, 1 reply; 26+ messages in thread From: Akira Yokosawa @ 2022-12-06 23:11 UTC (permalink / raw) To: Carlos Bilbao, corbet, ojeda; +Cc: linux-doc, linux-kernel, bilbao, konstantin On Tue, 6 Dec 2022 09:31:51 -0600, Carlos Bilbao wrote: > 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@amd.com> > --- > Documentation/Makefile | 4 ++++ > 1 file changed, 4 insertions(+) > > 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))) > What about patch below on top of this? This way, it is possible to skip rustdoc generation by saying: make CONFIG_RUST=n SPHINXDIRS=doc-guide htmldocs The reordering is to complete Sphinx runs even if rustdoc generation ends up in error. With this applied on top, Reviewed-by: Akira Yokosawa <akiyks@gmail.com> Thanks, Akira ------ diff --git a/Documentation/Makefile b/Documentation/Makefile index 2cf3e0fd7839..4d334468aaaf 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -92,12 +92,12 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) fi htmldocs: + @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) # If Rust support is available, add rustdoc generated contents -ifdef CONFIG_RUST +ifeq ($(CONFIG_RUST),y) $(Q)$(MAKE) rustdoc endif - @$(srctree)/scripts/sphinx-pre-install --version-check - @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) texinfodocs: @$(srctree)/scripts/sphinx-pre-install --version-check -- ^ permalink raw reply related [flat|nested] 26+ messages in thread
* Re: [PATCH v3 2/2] docs: Integrate rustdoc generation into htmldocs 2022-12-06 23:11 ` Akira Yokosawa @ 2022-12-07 0:06 ` Randy Dunlap 0 siblings, 0 replies; 26+ messages in thread From: Randy Dunlap @ 2022-12-07 0:06 UTC (permalink / raw) To: Akira Yokosawa, Carlos Bilbao, corbet, ojeda Cc: linux-doc, linux-kernel, bilbao, konstantin On 12/6/22 15:11, Akira Yokosawa wrote: > On Tue, 6 Dec 2022 09:31:51 -0600, Carlos Bilbao wrote: >> 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@amd.com> >> --- >> Documentation/Makefile | 4 ++++ >> 1 file changed, 4 insertions(+) >> >> 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))) >> > > What about patch below on top of this? > This way, it is possible to skip rustdoc generation by saying: > > make CONFIG_RUST=n SPHINXDIRS=doc-guide htmldocs > > The reordering is to complete Sphinx runs even if rustdoc generation > ends up in error. > > With this applied on top, > > Reviewed-by: Akira Yokosawa <akiyks@gmail.com> > > Thanks, Akira > Oh yes, I like both of those changes. Thanks. > ------ > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 2cf3e0fd7839..4d334468aaaf 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -92,12 +92,12 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) > fi > > htmldocs: > + @$(srctree)/scripts/sphinx-pre-install --version-check > + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) > # If Rust support is available, add rustdoc generated contents > -ifdef CONFIG_RUST > +ifeq ($(CONFIG_RUST),y) > $(Q)$(MAKE) rustdoc > endif > - @$(srctree)/scripts/sphinx-pre-install --version-check > - @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) > > texinfodocs: > @$(srctree)/scripts/sphinx-pre-install --version-check -- ~Randy ^ permalink raw reply [flat|nested] 26+ messages in thread
end of thread, other threads:[~2022-12-07 19:33 UTC | newest] Thread overview: 26+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2022-11-30 22:08 [PATCH] docs: Integrate rustdoc into Rust documentation Carlos Bilbao 2022-12-01 12:42 ` Miguel Ojeda 2022-12-01 20:40 ` Carlos Bilbao 2022-12-02 16:27 ` Miguel Ojeda 2022-12-02 16:30 ` Carlos Bilbao 2022-12-01 20:48 ` [PATCH v2] " Carlos Bilbao 2022-12-05 1:06 ` Akira Yokosawa 2022-12-05 16:08 ` Miguel Ojeda 2022-12-06 13:32 ` Akira Yokosawa 2022-12-06 15:02 ` Jonathan Corbet 2022-12-06 15:39 ` Miguel Ojeda 2022-12-05 16:36 ` Carlos Bilbao 2022-12-06 14:22 ` Akira Yokosawa 2022-12-06 14:55 ` Carlos Bilbao 2022-12-06 15:01 ` Carlos Bilbao 2022-12-06 15:31 ` [PATCH v3 0/2] " Carlos Bilbao 2022-12-06 15:31 ` [PATCH v3 1/2] docs: Move rustdoc output, cross-reference it Carlos Bilbao 2022-12-06 22:56 ` Akira Yokosawa 2022-12-07 8:27 ` Jani Nikula 2022-12-07 13:49 ` Carlos Bilbao 2022-12-07 14:15 ` Jani Nikula 2022-12-07 15:06 ` Carlos Bilbao 2022-12-07 19:33 ` Jonathan Corbet 2022-12-06 15:31 ` [PATCH v3 2/2] docs: Integrate rustdoc generation into htmldocs Carlos Bilbao 2022-12-06 23:11 ` Akira Yokosawa 2022-12-07 0:06 ` Randy Dunlap
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).