Implement automatic HTML generation

[mwoehlke]

Add automation via GitHub Actions to generate the specification HTML and deploy the same to GitHub Pages.

Additionally, rework HTML generation to use Poetry¹ to set up and manage a virtual environment used to generate the HTML. This helps ensure that both local and automated builds are using a uniform environment.

Note that deployment eschews the upload-pages-artifact² action because the mechanism used here allows us to bundle the files and correct their permissions in one command.

For clarity, the _ext directory is renamed to _extensions.

¹ https://python-poetry.org/
² https://github.com/actions/upload-pages-artifact/

Fixes #40. Supersedes #41.

[mwoehlke]

@bruxisma, I don't know how to non-invasively perform surgery on someone else's PR and #41 needed additional changes. I was also unable to get extension bundling with Poetry to work; please feel free to have another crack at that in a follow-up if you like. Also, please submit the spellcheck job as a separate PR; it's useful, but I don't think it should be bundled with HTML generation. (Not in the same commit, at least.)

[bruxisma]

I've been surreptitiously busy, so I've had to delay my time working on my PR. Please just ping me next time if you'd like the PR to be updated due to lack of response. It's easier than opening a second PR IMHO

[mwoehlke]

@bruxisma, I also want to be sure I can control the final commit message. The only other way I know (with confidence) to do that is to force-push to your fork, and I didn't want to do that. Plus, this way I wasn't blocked waiting on you.

[bruxisma]

When using a squash and merge to the default branch on github, you get control over both the commit subject and the message contents.

EDIT: to be clear you need to disallow the "merge" commit setting, and then upon "squash and merge" or "rebase and merge" being selected you get the option to change the commit subject and it's contents. This is afforded to every user with the ability to merge a given PR

[mwoehlke]

to be clear you need to disallow the "merge" commit setting

I don't want to disallow merges. I have a strong aversion to forcibly throwing out good history, and to becoming a project that does so.

upon "squash and merge" or "rebase and merge" being selected you get the option to change the commit subject and it's contents

That may be the case after I actually press the "merge" button? I'm not getting it beforehand, which means there seems to be no way to know that I will get the option except to risk merging something. This, alas, makes me hesitant to experiment.

[bruxisma]

I don't want to disallow merges. I have a strong aversion to forcibly throwing out good history, and to becoming a project that does so.

This is why I suggested keeping the rebase option on. A merge commits just shows a tree with the history. A rebase commit will be merged in with the history intact, but linearly so. A squash is good when you want to have a bunch of "wip. fix. wip" messages just thrown into one commit with the PR's description vs the actual commit message (though you also get the option to change that as well).

That may be the case after I actually press the "merge" button? I'm not getting it beforehand, which means there seems to be no way to know that I will get the option except to risk merging something. This, alas, makes me hesitant to experiment.

I didn't update that part as part of my edit, and apparently it has changed in recent years. All three can give you the option to change the commit message and description upon clicking the merge button now as long as you set it away from "Default Message" in the repository settings, as it'll then ask you to confirm with a second click. You can always test on a throwaway repository to try these things out.