[discussion]: Create PR previews for doc-related changes?

[joelostblom]

What would you like to discuss?

In a couple of previous docs-related projects I worked on, I set up preview deployments so that a link is posted where the built docs can be viewed. I found this quite useful as it automates the check for that the docs are still building and also allows the reviewer to not have to build locally each time.

The actions script would look something like this https://github.com/UBC-MDS/ds-toolbox/blob/main/.github/workflows/pr-preview.yaml and the PR then gets a comment from a bot with a link to the preview like so UBC-MDS/ds-toolbox#119

[lwjohnst86]

I'd considered that a while ago because Netlify (which is what we use to host the websites) allows deploy previews too. But it gets a bit too complicated to set up for (at least in our experience) little use or need (text changes don't need to be previewed to understand what will change, but I see the benefit for stylistic changes).

Not sure how this workflow would work for us. Would we have to have GitHub Pages enabled for this to work? Does that mean that there would be potentially two "live" sites for our websites, one from Netlify and another from gh-pages? That could have traffic going to both? If we used the PR only workflow, would that not still need to have the base gh-pages available? And when the PR is closed, what happens to the preview? I can't tell from your workflow that it deletes it. Does it?

[joelostblom]

Good questions! Seems like it might not be worth it for your use cases, but I'll reply to each of your questions:

I'd considered that a while ago because Netlify (which is what we use to host the sites) allows deploy previews too.

Ah, I didn't realize that you use Netlify instead of GH pages to serve the sites. Then the simplest would probably be to enabled it there, and if that is already too complicated then maybe it is not worth spending too much time on having another workflow for the reviews. I thought it was just a matter of toggling "Deploy previews" on for Netlify though and it will use the same build steps as for the main site to create the preview.

But it gets a bit too complicated to set up for (at least in our experience) little use or need (text changes don't need to be previewed to understand what will mudar, but I see the benefit for stylistic changes).

Agree that text changes don't really need to be reviewed in a PR preview, its more for rendering of things like callouts, grids, tables, etc.

Not sure how this workflow would work for us. Would we have to have GitHub Pages enabled for this to work?

Yes

Does that mean that there would be potentially two "live" sites for our websites, one from Netlify and another from gh-pages? That could have traffic going to both? If we used the PR only workflow, would that not still need to have the base gh-pages available?

Yes, gh-pages is required for the workflow I linked. Technically, each PRs will create a new live site with the URL modified to include the PR number so it is unlikely someone will actually come across the site related to the PR by chance.

And when the PR is closed, what acontece to the preview? I can't tell from your workflow that it deletes it. Does it?

Yes, the PR site lives in a folder with the PR number on the gh-pages branch. This folder should be deleted when the site is closed. This should happen automatically via the pr-preview action in the workflow, but occasionally it seems to not do the cleanup properly, like for the PR I linked which still has an active site for a closed PR (not sure if it is an issue with my config or the workflow action).

[lwjohnst86]

Hmm, seems the Quarto publish to Netlify GitHub Action doesn't support PR previews yet: quarto-dev/quarto-actions#33

And the workflow they link to there is way too complicated: https://github.com/mcanouil/mickael.canouil.fr/blob/main/.github/workflows/quarto-render.yml

We can keep this issue open and revisit it in the future though. Would be an interesting feature.

[joelostblom]

Sounds good! Note that there is a significantly more straightforward Netrlify-Quarto previw action workflow posted here https://github.com/quarto-dev/quarto-web/pull/667/files

[lwjohnst86]

Wow that is much better!

[lwjohnst86]

I'll move this over into template-website, since it is more relevant there.