Incorporating Rust support documentation into Zephyr's docs

[d3zd3z]

Introduction

With support for Rust applications now in an (optional) module, this proposal discusses what is needed to also make this well documented.

Problem description

There are two kinds of documentation for supporting applications written in Rust on Zephyr:

• User Docs: This would be part of the Zephyr project docs, under the support for languages. This will be created and maintained the same way other project docs are maintained. The only possible concern is that this is a module.
• Rust Docs: The rust language has it's own mechanism for document Rust interfaces. Ideally, all interfaces that can be used to work with Zephyr from Rust will be well documented. Rust has good tools to generate this from specially formatted comments in the source (similar to doxygen, but no external tooling is needed, other than the same tools needed to build rust code).

Proposed change

• The user docs will be written and maintained the same as any other primary docs in Zephyr.
• The Rust interfaces will be documented using rustdoc comments in the code. The rust compiler can enforce the presence of documentation, and even check cross references and other similar issues at compile time.
  • The zephyr-lang-rust repo will gain a workflow that builds the docs, and publishes them in a similar way to have docs are published on PRs on the Zephyr project. The location for this has been determined, and keys made available for this workflow to be able to publish these docs.
  • The zephyr-lang-repo will also publish docs, in a similar place, that represent the current state of "main" in the repo. This will be useful for users who wish to use a more recent version of zephyr-lang-repo without having to render their own docs (optional?)
  • The doc workflow for main on zephyr will generate rust docs at part of doc generation time, and these will be placed next to where the doxygen docs are placed.
  • Extensions will be made to the RST processor to provide an easy way to link to Rust docs in the tree.

Detailed RFC

The per-pr documentation is being worked on in zephyrproject-rtos/zephyr-lang-rust#3. Because many features depend on an exact config and dts, it is necessary to generate this documentation in the context of a specific build. At this time, I have chosen a target where the most number of features can be enabled, in order to generate the most complete docs.

Additional workflow steps will be needed to render the docs upon changes merging onto the 'main' branch.

For the main project docs, it will be necessary to incorporate this into the existing Zephyr documentation workflow (or alongside it). The Rust tools generate documentation into a tree of html, and it may be worthwhile to place a few index.html files in key places to make these easier to navigate. The docs can then be pushed an adjacent directory to the current docs.

Proposed change (Detailed)

There are actually two runs of the documentation generation process for the Zephyr Rust support. One generates the docs for the zephyr crate that will be the primary interface users will use to work with Rust code on Zephyr. The other generates docs for the tools and utilities that are run at build time. This will be of use to those interested in how these tools work, or in improving or fixing them.

Each of these docs are generated from an actual Zephyr application. Although it isn't necessary to make a full build, it will be necessary to run enough of the build to generate the generated files that Rust's bindgen tools uses to make the interfaces. Likely this can be done with a cmake target that will generate the docs for the given application.

After the docs are generated, they will be placed under build/rust/... in a place determined by the tools, and can be collected to published.

Dependencies

There shouldn't need to be any additional tooling beyond the tools already in place to compile Rust code.

Concerns and Unresolved Questions

• Sometimes it might be challenging to determine if a given piece of documentation should be placed on the Rust side or within the Zephyr project docs.
• Additional time to run doc generation on Zephyr.

Alternatives

The Rust ecosystem has a documentation publishing system in place for crates that are published to crates.io. Unfortunately, the current rust support cannot be published there, because it depends heavily on not just the Zephyr sources, but a particular build of Zephyr. Also, the versioning and release process between crates.io and Zephyr is fairly different.

It would be possible to not generate the documentation, and instead provide instructions for users to run the build target that generates it for them. These docs are viewable locally. This is a bit less convenient for the user, but does have the advantage of giving them documentation for their exact configuration (if features are disabled, those items don't show up in the docs).