Include HTML output generated with rustdoc into the Linux kernel
documentation on Rust.
Carlos Bilbao:
docs: Move rustdoc output, cross-reference it
docs: Integrate rustdoc generation into htmldocs
---
V7 is https://lore.kernel.org/lkml/[email protected]/T/#m5dcab9c7775e85331c0d067d411fe246ed39af1e
Changes since V7:
- Use lowercase for rustdoc_output and define it with `:=`.
- Remove messages that would be printed when skipping Rust documentation.
V6 is https://lore.kernel.org/lkml/20230127165728.119507-1-carl...
Changes since V6:
- Skip Rust document generation entirely if .config doesn't exist.
Changes since V5:
- Continue executing htmldocs even if rustdoc fails.
Changes since V4:
- Limit rustdoc note only to html outputs.
Changes since V3:
- Added Reviewed-Bys from Akira Yokosawa.
- PATCH 1/2: Avoid error 404 adding tag `rustdoc` for Sphinx.
- PATCH 1/2: Don't use "here" as link text, describe destination instead.
- PATCH 2/2: Check CONFIG_RUST in a way that allows us to skip generation.
- PATCH 2/2: Reoder Sphinx runs so they complete even if rustdoc fails.
Changes since V2:
- Split v2 into two-patch series.
- Add "only:: html" directive in Documentation/rust/index.rst reference
Changes since V1:
- Work on top of v6.1-rc1.
- Don't use rustdoc.rst, instead add link to Documentation/rust/index.rst.
- In Documentation/Makefile, replace @make rustdoc for $(Q)$(MAKE) rustdoc.
- Don't do LLVM=1 for all rustdoc generation within `make htmldocs`.
- Add spaces on definition of RUSTDOC_OUTPUT, for consistency.
---
Documentation/Makefile | 16 ++++++++++++++++
Documentation/rust/index.rst | 8 ++++++++
rust/Makefile | 15 +++++++++------
3 files changed, 33 insertions(+), 6 deletions(-)
Change target `make htmldocs` to combine RST Sphinx and the generation of
Rust documentation, when support is available and .config exists.
Reviewed-by: Akira Yokosawa <[email protected]>
Signed-off-by: Carlos Bilbao <[email protected]>
---
Documentation/Makefile | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 023fa658a0a8..2f35793acd2a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -59,6 +59,12 @@ PAPEROPT_letter = -D latex_paper_size=letter
KERNELDOC = $(srctree)/scripts/kernel-doc
KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
+ifneq ($(wildcard $(srctree)/.config),)
+ifeq ($(CONFIG_RUST),y)
+ # Let Sphinx know we will include rustdoc
+ ALLSPHINXOPTS += -t rustdoc
+endif
+endif
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
@@ -95,6 +101,16 @@ htmldocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
+# If Rust support is available and .config exists, add rustdoc generated contents.
+# If there are any, the errors from this make rustdoc will be displayed but
+# won't stop the execution of htmldocs
+
+ifneq ($(wildcard $(srctree)/.config),)
+ifeq ($(CONFIG_RUST),y)
+ $(Q)$(MAKE) rustdoc || true
+endif
+endif
+
texinfodocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
--
2.34.1
On 7/18/23 12:15, Carlos Bilbao wrote:
> Change target `make htmldocs` to combine RST Sphinx and the generation of
> Rust documentation, when support is available and .config exists.
>
> Reviewed-by: Akira Yokosawa <[email protected]>
> Signed-off-by: Carlos Bilbao <[email protected]>
> ---
> [...]
Reviewed-by: Martin Rodriguez Reboredo <[email protected]>
Carlos Bilbao <[email protected]> writes:
> Include HTML output generated with rustdoc into the Linux kernel
> documentation on Rust.
>
> Carlos Bilbao:
> docs: Move rustdoc output, cross-reference it
> docs: Integrate rustdoc generation into htmldocs
So I've been messing with this a bit, trying the various combinations.
- With no .config file, it behaves as it always did - thanks.
- With CONFIG_RUST=y I get the rustdocs, as expected. There is a time
penalty of about 5%, which is unfortunate, but that's the cost of
progress, I guess.
- Setting CONFIG_RUST=n led to a crash with make complaining:
"No rule to make target 'rustdoc'". That isn't something I have been
able to reproduce, though, so I have no idea what happened there; have
you ever seen this?
Other than that one bit of strangeness, I think this is about ready to
be applied.
Thanks,
jon
Jonathan Corbet <[email protected]> writes:
> Other than that one bit of strangeness, I think this is about ready to
> be applied.
...and I've just gone ahead and done that - thanks for doing this and
sticking with it!
jon
On 7/20/23 17:46, Jonathan Corbet wrote:
> Carlos Bilbao <[email protected]> writes:
>
>> Include HTML output generated with rustdoc into the Linux kernel
>> documentation on Rust.
>>
>> Carlos Bilbao:
>> docs: Move rustdoc output, cross-reference it
>> docs: Integrate rustdoc generation into htmldocs
>
> So I've been messing with this a bit, trying the various combinations.
>
> - With no .config file, it behaves as it always did - thanks.
>
> - With CONFIG_RUST=y I get the rustdocs, as expected. There is a time
> penalty of about 5%, which is unfortunate, but that's the cost of
> progress, I guess.
>
> - Setting CONFIG_RUST=n led to a crash with make complaining:
> "No rule to make target 'rustdoc'". That isn't something I have been
> able to reproduce, though, so I have no idea what happened there; have
> you ever seen this?
I have not been able to reproduce this error either. If anyone comes across
this error in the future, please reach out to the list.
>
> Other than that one bit of strangeness, I think this is about ready to
> be applied.
>
> Thanks,
>
> jon
Thanks,
Carlos