Open d3zd3z opened 1 day ago
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?
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:
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.pr/123/docs
location, it would make sense to have amain/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:
For publishing to gh-pages:
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:
There are possibly other places to publish the docs, but these don't seem to have any particular advantage over the proposed solutions.