mbox series

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

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

Message

Carlos Bilbao Jan. 27, 2023, 4:57 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

---
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       | 10 ++++++++++
 Documentation/rust/index.rst |  8 ++++++++
 rust/Makefile                | 15 +++++++++------
 3 files changed, 27 insertions(+), 6 deletions(-)

Comments

Jonathan Corbet Feb. 3, 2023, 5:55 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 spent a fair while messing with this, really hoping to get it
merged for 6.3, but I think it's still just too fragile.

- With a too-new version of bindgen it kills the htmldocs build
  entirely.  If we can't build the Rust docs successfully with the
  toolchain that the user has installed then so be it, but it shouldn't
  wreck the docs build entirely.

- It still throws the user into the "make oldconfig" process, which is
  unexpected for a docs build.  This happens even on a system with no
  Rust installed at all.

- I dumped my Fedora toolchain and did the curl|bash ritual to set up
  the proper versions with rustup.  It would be nice to have some better
  documentation on how to do that ... *how* to install bindgen may not
  be obvious to all users.  It also failed until I installed lld
  separately.

On a system with the right tool versions, and with a kernel already
configured to build the Rust support, it worked nicely, though.

I'd really like to see a solution that (1) doesn't kill the docs build
process if the tool versions are wrong, and (2) doesn't force the
creation of a kernel configuration.  What are our chances of getting
there?

Thanks,

jon
Miguel Ojeda Feb. 4, 2023, 12:05 a.m. UTC | #2 
On Fri, Feb 3, 2023 at 6:55 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> - I dumped my Fedora toolchain and did the curl|bash ritual to set up
>   the proper versions with rustup.  It would be nice to have some better
>   documentation on how to do that ... *how* to install bindgen may not
>   be obvious to all users.  It also failed until I installed lld
>   separately.

Are you referring to the Quick Start guide? I am asking because the
guide has a one-line command ready for copy-paste to install
`bindgen`, so I guess you mean something else (?). It also notes that
there are standalone installers available (if you don't want `rustup`)
-- I will change the URL to point directly to the page with the
installers, though, since that should help.

The script behind `make rustavailable` is getting a bunch of
improvements (and tests) in an ongoing patch series -- I will check
the `lld` issue for v2 too. If you don't mind it, I will Cc you then,
in case you could give it a try and confirm it helped.

Thanks!

> I'd really like to see a solution that (1) doesn't kill the docs build
> process if the tool versions are wrong, and (2) doesn't force the
> creation of a kernel configuration.  What are our chances of getting
> there?

It may be quite involved, since a few artifacts from the normal build
would be needed [1]. Since some things in the build system will likely
change anyway, it is probably best to come back to this after that.
What do you think, Carlos? Or would you like to give it a try?

[1] https://lore.kernel.org/linux-doc/CANiq72mC+WzOxhZVtEvnsFYzuBPkd51=TYXK01ztcTZ-CAcUiw@mail.gmail.com/

Cheers,
Miguel