Deploy generated docs from PRs

[martinjaeger]

Is your enhancement proposal related to a problem? Please describe.

Changes affecting the Documentation are often hard to review if you can't browse the final generated HTML pages.

As pointed out by @henrikbrixandersen, the build artifacts can be downloaded. However, this involves some additional steps by the reviewer (click through the GH Actions results, download the file locally, unzip it, browse to the location).

It would be nice to be able to view the updated docs with a single click.

Describe the solution you'd like

GitHub pages could be used to deploy the generated docs for each PR.

If they are stored in the gh-pages branch in a subfolder pr/12345, the website will be accessible under https://zephyrproject-rtos.github.io/zephyr/pr/12345.

Necessary actions

1. Enable gh-pages feature
2. Add additional GitHub action to deploy docs for PRs

Ideally, a bot would automatically add a link to the rendered docs in the PR.

I'd be willing to create a PR for the GH action workflow.

Security considerations

It is a potential security risk to automatically deploy something based on a PR that can be created from anyone on the internet. However, I think in this case the risk is acceptable:

• GitHub pages only allows static websites, so the main risk would be malicious JavaScript code.
• We are not deploying to any official Zephyr website.
• Malicious JavaScript code would have to go through the Doxygen/Sphinx/Breathe chain. Not sure if it's possible to inject JavaScript into the generated websites.
• It seems to be possible to configure certain actions to be manually triggered by a maintainer/collaborator, which could make sense for the final deployment step.

CC @carlescufi @gmarull @nashif

[gmarull]

+1 on getting docs preview. Due to the size of built docs ~400Mb, I'm not sure if gh-pages would be a suitable solution (see https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#limits-on-use-of-github-pages).

One solution would be to use https://readthedocs.org/ as they seem to offer this capability, but they just support the standard Sphinx workflow. Sphinx usage in Zephyr is nowadays in pretty good shape, but we still have custom scripts to generate Kconfig/DT pages or docs out of doc/, both non-standard stuff that rtd can't support. I think fixing those would be a good idea. Another solution would be to have a simple HTTP server, as sdk-nrf does.

[martinjaeger]

Good point. I didn't realize the docs are that big. Even if GH pages allowed more storage, having a gh-pages branch with all these files is probably not a good idea as it would dramatically increase the size of the repo that is cloned by everyone (if one does not clone/pull a specific branch).

The Nordic approach with a dedicated HTTP server looks great.

I removed "GH pages" from the title and will keep the issue open.

[nashif]

we used to push the output into amazon S3 and provide a link. Publishing the data to S3 should be straightforward, we just need the documentation action to publish a comment about where to find the published docs. On the S3 side, we can do automatic cleanup, i.e. delete PR docs older than 2 weeks or something...

[gmarull]

we used to push the output into amazon S3 and provide a link. Publishing the data to S3 should be straightforward, we just need the documentation action to publish a comment about where to find the published docs. On the S3 side, we can do automatic cleanup, i.e. delete PR docs older than 2 weeks or something...

I could work on that if I can get an S3 bucket and credentials :-)

[gmarull]

This feature was implemented in #44246, closing