Great, thanks! How hard would it be to deploy the documentation somewhere as a preview for the PR?

Depends on how and where, if we vendor lock ourselves and use something like vercel previews, pages.dev etc it's legitimately a single command at the end, if we want to adjust murdocks I don't fully know what to change and it might be more complicated. This is the one shortfall of github pages compared to nearly all other static site hosts nowadays.

Generally I'd also really like a preview being deployed but the combination of this ci test with the markdown that's mostly github compatible might be the easier choice for now. You shouldn't be missing out too much unless a PR adds crazy MDX content which github cant render.

if we vendor lock ourselves and use something like vercel previews, pages.dev etc it's legitimately a single command at the end

Is it really a vendor lock-in though if we can simply switch / disable the preview at any time if needed? I think it's still valuable to see the whole guide site deployed, and not just the single markdown files on Github.

I would not block a preview feature but I do think: we do not need that extra complexity. Once the "functional" PRs for the guides are in, we will only/mostly see content PRs. Content PRs are reviewable by code and the markdown rendering of GitHub. Yes it is not perfect but if one has doubts that the PR author did not test if it would render correctly via starlight, you can still checkout the changes locally and quickly run make doc-starlight and see for yourself. I believe it is not worth our time and the added complexity to build a preview deployment for guides.
After all, it is not doxygen that breaks violently when one misses a bracket or something.

I tend to agree if it really is complex to be added, but @AnnsAnns made it sound above like it would be very easy to add, and in that case I'd say the benefits outweigh the costs.

The complexity would probably come from the fact that it would require RIOT to have some kind of official account at one of the web providers and we would have to deal with secrets etc. which means a bit of coordination would be required.

After further investigation I found this action that deploys to gh pages. This might work without those issues but I haven't tested it yet. I'll try to test it on something like my blog which has a similar tech stack and report back whether adding this would be complex or not. If it's not too complex and works well we could add this, if it is complex or has some downsides I'd probably just ignore this for now.

It works*
(*on my blog there are a lot of permalinks which don't properly adjust to the baseUrl, this shouldn't be the case for the guide. It also required some minor adjustments to dynamically set the baseUrl).

AnnsAnns/Bort#17
https://annsann.eu/pr-preview/pr-17/ramblings/

Nevermind, I just realized a critical flaw in this. RIOT PRs don't come from different branches, they come from different forks. This solution does not account for that (given that this would allow any person to "commit" stuff into the RIOT gh-pages branch).

I will revert my commit. The only way this would work would be for forks to enable github pages which isn't an automatic process and would result in CI errors if not enabled.

Please squash!

squashed

Murdock results

✔️ PASSED

67f88e5 .github/workflows: Guide Site Build Test

Artifacts

• Documentation preview