chore: add workflow to preview docs PRs on Netlify

[amoeba]

Creates a new workflow that publishes the docs to Netlify for PRs that touch paths related to the docs. This uses an Environment to make access of the secrets require approval by an admin. It only triggers when the PR touches mkdocs.yml or any path inside ./docs.

The reason this is being done as a workflow is because Netlify's PR deploy previews are an all-or nothing thing meaning it would create deploy preview for even non-docs PRs and also add a noisy comment about the preview. The workflow approach gives us control over which PRs we run deploy previews for at the cost of extra complexity on the setup.

Closes #62

[amoeba]

I think we can't test this easily until we've merged. I did a fair bit of looking around and it looks like you just can't access Environment secrets (which we're using) if the workflow is pull_request. So I'm trying pull_request_target which should be able to access Environment secrets. But we can't test that here because GitHub doesn't run pull_request_target workflows on the PRs that add them I guess.

[lidavidm]

I guess we're protected by needing approval but this is kind of a footgun with pull_request_target.

[lidavidm]

AIUI, on a pull_request_target trigger this checks out the repository on the target branch and not the pull request (quite intentionally), so this won't do what you want.

[amoeba]

ah, okay. The docs around this use "in the context" which is a thing I don't know what it is and I couldn't tell which checkout you get.

[lidavidm]

https://github.com/orgs/community/discussions/22363#discussioncomment-3236409 is probably a better summary than the docs themselves (oops)

[amoeba]

nice, thanks

[amoeba]

I'm going to close this for now. The risks and complexity aren't worth the benefits.