mbox series

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

Message ID 20230718151534.4067460-1-carlos.bilbao@amd.com
Headers
Series docs: Integrate rustdoc into Rust documentation |

Message

Carlos Bilbao July 18, 2023, 3:15 p.m. UTC 
  Include HTML output generated with rustdoc into the Linux kernel
documentation on Rust.

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

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

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

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

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

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

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

Changes since V1:
 - Work on top of v6.1-rc1.
 - Don't use rustdoc.rst, instead add link to Documentation/rust/index.rst.
 - In Documentation/Makefile, replace @make rustdoc for $(Q)$(MAKE) rustdoc.
 - Don't do LLVM=1 for all rustdoc generation within `make htmldocs`.
 - Add spaces on definition of RUSTDOC_OUTPUT, for consistency.

---
 Documentation/Makefile       | 16 ++++++++++++++++
 Documentation/rust/index.rst |  8 ++++++++
 rust/Makefile                | 15 +++++++++------
 3 files changed, 33 insertions(+), 6 deletions(-)

Comments

Jonathan Corbet July 20, 2023, 10:46 p.m. UTC | #1 
Carlos Bilbao <carlos.bilbao@amd.com> writes:

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

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

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

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

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

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

Thanks,

jon
Jonathan Corbet July 21, 2023, 9:43 p.m. UTC | #2 
Jonathan Corbet <corbet@lwn.net> writes:

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

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

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

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

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

Thanks,
Carlos