first pass at a GitHub Pages publishing shared workflow

[briantist]

This is a reusable workflow for publishing to GitHub Pages.

This is intended to be an opinionated, specific way of doing so that supports multiple simultaneous docs builds within a single GitHub Pages site, not a general workflow to have a high degree of customizability.

The reason for that, is that the bulk of the "work" of publishing to GH pages is handled by a single action, peaceiris/actions-gh-pages, which can be used directly for anyone wishing to do something simpler or more custom. Alternatively, "publishing" to GitHub Pages is done via commit and push, so users who don't want to use the action can similarly put something together using git commands.

Or this workflow can have the destination-dir overridden, which is really where our convention is applied.

About the convention used

When destination-dir is not set, this workflow puts docs into sub-directories in the published site based on the event:

• for a pull request, the site is published to /pr/XX where XX is the PR number, for example: /pr/123
• for a push to a branch, the site is published to /branch/NAME, for example: /branch/main or /branch/stable-3
• for a push to a tag, the site is published to /tag/TAG, for example: /tag/3.21.7

Since the consumer of the workflow completely controls the triggers of their calling workflow, anyone who wants to limit which sites get published can do so by limiting the workflow triggers (triggering on only PRs or pushes, limiting the branches and tags, etc.); this does not need customization in the workflow.

I will post a getting started guide to initially setting up GH pages, but it is pretty straightforward.

---

Not supported

• intermingling with an existing GH pages site (could work with static [non-jekyll] site if you understand the directory structures, use at your own risk)
• publishing to a GH pages site in another repo (this one is quite possible to implement, and may be desirable for some, good future improvement)
• single commit/orphan commit/force push (this is something I want to support, as it will help keep bloat down, but at the moment can't be done with our convention until maybe v4 of the action we use: keep_files=true does not work when force_orphan=true peaceiris/actions-gh-pages#455)
• other things I didn't call out explicitly

Also, right now there's no straightforward way to have this publish arbitrary branches/tags that were pushed before this was in place. It can be done (in the consuming repo) by adding a workflow_dispatch trigger with an input of the branch or tag, and then you'd have to set destination-dir yourself following the convention. That would work for one-at-a-time. For outside of actions, some separate script could render all the docs for the various refs, put them in the correct directories, and push them up.

[briantist]

Merging right away because:

• It's a new workflow; doesn't affect anyone unless they use it explicitly
• I want to start dogfooding it
• I did do tests on my own fork of an upstream collection; now I want to more fully use it

[briantist]

Closes #34