Add documentation for Rust support

[d3zd3z]

This brings in some basic documentation for Rust support, as well as adding workflow support to build the rust docs as part of CI.

[zephyrbot]

The following west manifest projects have changed revision in this Pull Request:

Name	Old Revision	New Revision	Diff

✅ All manifest checks OK

Note: This message is automatically posted and updated by the Manifest GitHub Action.

[gmarull]

Is west really needed to build rust docs? Also, why is a board required? I'm a bit surprised that rust docs are not generated on its own repo.

[d3zd3z]

We do generate rust docs in that repo, but they aren't correlated with any particular Zephyr release. This builds the rust docs that are specifically the version brought in.

As far as why west and a board are needed:

• The rust code uses bindgen to generate bindings to the Zephyr API. In order to parse headers, the generated header files are needed, this requires much of the build tools to get that far.
• The rust docs will be generated based on specific Kconfig values. The docgen app is intended to enable as many as possible in order to get the fullest docs.
• Picking a specific board will make the contents of the docs, specifically for zephyr::raw also specific to that board. I intend to have instructions in the docs for Rust explain how to generate and view the docs locally, so developers can have those be accurate for their configuration and board. But, we need something so that we can reference the docs.

[d3zd3z]

I'm a bit surprised that rust docs are not generated on its own repo.

They are. But, using them in the main docs would be a bit complicated logistically. Namely, we currently generate docs for each PR in the rust repo. These will stick around for I think two weeks. We also generate docs for main (well, we will, there is a small issue to fix that), but these are replaced each time a change is merged. If we wanted to directly use that artifact from here, we'd need to also generate them for specific shas, and somehow know to only retire those when a manifest doesn't refer to them. It would have to check every possible branch's manifest (there will be backport branches after the first release containing this).

It seems just easier to regenerate them in the Zephyr repo for the correct version, that way they'll persist according to the rules here (for each PR, the two weeks, and latest getting updated).

[gmarull]

We do generate rust docs in that repo, but they aren't correlated with any particular Zephyr release. This builds the rust docs that are specifically the version brought in.

As far as why west and a board are needed:

• The rust code uses bindgen to generate bindings to the Zephyr API. In order to parse headers, the generated header files are needed, this requires much of the build tools to get that far.

I understand you need a build target, but picking a nordic board feels weird unless explained. I'd rather choose some vendor-agnostic target.

• The rust docs will be generated based on specific Kconfig values. The docgen app is intended to enable as many as possible in order to get the fullest docs.

Is it using https://github.com/zephyrproject-rtos/zephyr/blob/main/doc/_extensions/zephyr/kconfig/__init__.py#L133 ?

• Picking a specific board will make the contents of the docs, specifically for zephyr::raw also specific to that board. I intend to have instructions in the docs for Rust explain how to generate and view the docs locally, so developers can have those be accurate for their configuration and board. But, we need something so that we can reference the docs.

Maybe you should instead create a "rustdoc" board as a build target that enables as much zephyr raw as possible for docs purposes. In general, I don't think rust users should really bother about the APIs exposed depending on the board... And zephyr::raw should likely be kept as something internal people should not rely on their apps.

[d3zd3z]

I understand you need a build target, but picking a nordic board feels weird unless explained. I'd rather choose some vendor-agnostic target.

I could do one of the qemu targets. I think this will be reasonably complete, as most shouldn't depend on the particular devices that are present. Someone wanting to navigate the rust version of their devicetree really needs to be generating docs locally for their specific build anyway.

[d3zd3z]

In general, I don't think rust users should really bother about the APIs exposed depending on the board

Where this really matters is with the generated modules representing their current device tree. The user will need to use this to be able to get instances of the devices on their platform. And, this doesn't make sense to have it be generic.

[nashif]

This is an optional module. doc builds and workflows should not depend on optional modules. Basically we now will be building the rust docs and publishing them on each PR and few times a day? This also pushes generated docs of an optional module to https://docs.zephyrproject.org/, is this what we want with any optional module? shouldn't all of this be published i.e. in the module GH domain instead and just linked? I think this requires some more discussion and thought.