Publishing generated rustdocs for zephyr-lang-rust docs

[d3zd3z]

Introduction

The zephyr-lang-rust repo contains several crates (units of Rust compilation) for this support. Rust has a mechanism, rustdoc, which works similarly to doxygen in that it generates html pages containing the API documentation directly from the rust code. This proposal covers how to make these rendered documents available.

Problem description

Currently, code added to the main Zephyr repo, that makes documentation changes, will trigger a doc build. This will place a preview of the documentation under a url, such as https://builds.zephyrproject.io/zephyr/pr/123/docs/, and a few other directories. This is linked to from the actions page on the PR, and allows a developer who is making documentation changes to preview these. Once the change merges, the doc build runs again on main, and this is pushed to the 'latest' directory of the main documentation.

Proposed change

There are two parts of this:

• For the version of zephyr-lang-rust that is brought into the optional.yaml file, I propose that the current Zephyr doc build should also include the generation of rustdocs, and these can be placed in a similar manner to how the doxygen generated documentation is done. This is just a simple change, and isn't likely to need TSC approval.
• For the zephyr-lang-rust documentation generated under PRs, there are two proposals.
  • The generated docs can be placed under https://builds.zephyrproject.io/zephyr-lang-rust/pr/123/docs, similar to the zephyr repo.
  • The generated docs could be placed under the gh-pages directory with a similar directory structure.
    In either situation, in addition to the pr/123/docs location, it would make sense to have a main/docs render, as this would be useful for developers who are using main on this branch rather than the current manifest version in the Zephyr repo.

Detailed RFC

For publishing to builds.zephyrproject.io, two things are needed:

• Add doc publishing code to a zephyr-lang-rust workflow that is similar to the one on main. The doc generation is already present in Add cargo doc generation and publishing. zephyr-lang-rust#3.
• Provide the S3 secrets for publishing to workflows running on this repo.

For publishing to gh-pages:

• Github already provides credentials for gh-pages publishing, which is effectively write access. This is typically done through a separate branch of the repo. Github provides actions for gh-pages publications, but, unfortunately, they do not allow publishing to subdirectories, and replace the entire generated tree. This will either require writing new actions, or locating one that performs this operation.
• Developing the workflow to do the publishing.
• In addition, scripts will be needed to clean the generated pages up over time, at least if storage becomes an issue. The gh-pages is under free usage, and subject to specific limitations from github.

Proposed change (Detailed)

I believe most is described above.

Dependencies

Adding rustdoc generation to the main documentation build will slightly slow down the existing documentation build. This currently takes 2 minutes, but this build is also installing the necessary rust toolchain, and cloning the Zephyr repo. Since both of these are already done in CI, this will likely be less time, (about 40 seconds for the above mentioned PR).

The generation on builds will run as a workflow on the zephyr-lang-rust repo, which are running on Github runners.

Concerns and Unresolved Questions

The main question is which of these approaches to take.

Alternatives

The other suggestion that has been given is to use docs.rs. There several reasons this is not tenable:

• docs.rs only generates documentation for crates on crates.io. Because the zephyr crates cannot be built outside of the context of a specific Zephyr build, it is not possible to publish these on crates.io.
• docs.rs only generates documentation for releases. We want documentation available for individual PRs, as developers should have this available, and it will make generated better, with the feedback.

There are possibly other places to publish the docs, but these don't seem to have any particular advantage over the proposed solutions.

[d3zd3z]

A little more investigation on gh-pages. There seem to be some workarounds to allow PR and preview deployments of the documentation, but they are based on the "legacy" way of publishing, which involves pushing to a gh-pages branch in the repo. Not sure of the security implications of this, as it means that the workflow would need the ability to write to the repo.

It's almost bizarre that they would develop an api for gh-pages without even just a preview ability. Who in their right mind would just publish untested changes?