chore: add a new gha to build and host an open PR

[Sita04]

New PR preview workflow:

• Adds a .github/workflows/pr-preview.yaml workflow that builds and deploys a MkDocs preview site for pull requests labeled with "build-preview", using the rossjrw/pr-preview-action to manage the preview lifecycle.
• Includes a cleanup job to automatically remove the preview when the PR is closed or the "build-preview" label is removed.

How to use this:

1. Create a PR
2. Add the label 'build-preview' to the PR to host the branch

Fixes #614

[koverholt]

Thanks for this! I experimented with the same plugin before (and a few other options).

My one drawback was that it will publish preview docs to the same docs endpoint as the main docs, so how can we ensure that those preview docs don't get indexed and end up in search results when they are not yet merged / published? Perhaps by using robots.txt, or publishing to a different endpoint, or something else?

[koverholt]

If we do enable / merge this functionality, I would suggest having build preview for all PRs rather than having to add a label.

[Sita04]

I thought about this as well. If we enable this by default, then do you think we might end up with tens/ hundreds of open hosted sites, potentially even for minor changes?

Couldn't weight in which direction to take, so thought if someone wanted to visualize, then it could be as simple as adding a label?

[koverholt]

I like that this action cleans up the PR after it's closed or merged, so in theory it would be one hosted preview site, with one URL path for each preview on the same base URL / site. And previews for all PRs would help authors review their rendered changes since folks don't always spin up mkdocs locally in dev and preview the rendered versions. So I am +1 to having it on for every PR by default, and ideally the plugin would handle the permutations and cleanup cleanly like this plugin does.

[joefernandez]

My one drawback was that it will publish preview docs to the same docs endpoint as the main docs, so how can we ensure that those preview docs don't get indexed and end up in search results when they are not yet merged / published? Perhaps by using robots.txt, or publishing to a different endpoint, or something else?

We don't want the preview content to be shown with the approved and merged content. That will create user confusion and potentially disrupt the browsing experience for the currently published content (especially for PRs where we are reorganizing content and temporarily breaking the browsing experience). Can we push the preview versions to a separate Preview site?

[Sita04]

@koverholt Excellent point! I've added the robots.txt to disallow indexing. Hope this is sufficient to prevent crawling.

@joefernandez All the PRs will be hosted under the pr-preview directory: https://google.github.io/adk-docs/pr-preview/pr-{number}/

"/pr-preview/pr-{number}/" will not be present for the actual hosted docs. But I do understand the concern of having it in the same domain. Let me check if we can change the domain.

[koverholt]

Can we push the preview versions to a separate Preview site?

The good news is that the pr-preview-action supports a different base URL for previews, but the bad news is there is not an easy way to do this with GitHub pages in terms of hosting more than one docs endpoint, like you can with Netlify or Vercel or other static site hosts. We would need to set up a separate static host for this using Firebase or Cloudflare Pages (like Jules does for PR previews) and manage it ourselves, which is sub-optimal.

@Sita04, are there other approaches or plugins that might make this easier, or is our limiting factor that GitHub Pages will only serve one docs endpoint in a given repo (and thus we would need a separate static hosting pipeline in any case)?

[Sita04]

are there other approaches or plugins that might make this easier, or is our limiting factor that GitHub Pages will only serve one docs endpoint in a given repo?

You are correct - only one endpoint per repo. And +100 to not creating overhead by adding Firebase/ Netlify.

This leaves with one other workaround if we want domain separation - we can create an empty adk-docs-previews repo and use that domain to host all previews.

edit: On a second thought, this doesn't entirely solve our problem though. We still have to add robots.txt to the other public repo and there's a potential to mess with the SEO as well.

[koverholt]

This leaves with one other workaround if we want domain separation - we can create an empty adk-docs-previews repo and use that domain to host all previews.

This was also the same conclusion I came to when I was experimenting with this before. However the "preview" repo would need to be always synced with the adk-docs repo (including PRs), and the action would need to run from the "preview" repo so that it publishes into the gh-pages branch in that repo, correct? In the end, the coupling of these two repos would need to be more complex than I originally thought rather than just an empty repo / placeholder for the domain.

[Sita04]

However the "preview" repo would need to be always synced with the adk-docs repo (including PRs), and the action would need to run from the "preview" repo so that it publishes into the gh-pages branch in that repo, correct?

I was thinking more on the lines of: "The GHA runs in the adk-docs repo and only the final html pages will be git pushed to the other repo's gh-pages". So, essentially the docs-preview repo will be empty except for the rendered html pages in different branches. wdyt?

Since Google has Enterprise version, we might even be able to create a privately hosted Github pages for review.

[koverholt]

The GHA runs in the adk-docs repo and only the final html pages will be git pushed to the other repo's gh-pages.

Got it, I see that option in the action's settings now. This pipeline makes the most sense to me since in theory we would only need to change the deploy-repository and pages-base-url setting for this to work. I think this is worth setting up and seeing if it behaves as we expect. And we could still have robots.txt just to guard the preview-repo's site and directory from getting indexed at all.