Add a CI check to verify docs are up-to-date

[dicej]

This would presumably involve running pydoc3 per the CONTRIBUTING.md instructions and then using diff to see if there are any changes.

[vdice]

I was thinking along these same lines and couldn't decide between the approach above or some alternates I'll list here:

• We could create a workflow triggered by merges to main wherein, if there is a diff in docs, push a commit as a github bot/actor with the changes straight to main.
• Don't even track docs on main but have a dedicated workflow, again triggered by merges to main, to (re-)generate and deploy them to the current GH pages site, potentially from a dedicated gh-pages branch holding the historical pre-v4 docs and all current, (re-)generated docs based on the contents from main. I'd have to refresh my memory but I think this is a standard approach to publishing GH pages sites.

At a higher-level, since it isn't envisioned that humans will directly edit the contents of docs/ (and assuming it is intended to stay that way), handling it all out-of-band and separate from contributor PRs/commits seems ideal.

[dicej]

The second option in your list seems ideal to me, but I'd suggest a couple of tweaks:

• Organize the docs into v1, v2, v3, v4, (and future vX major versions to come), and canary directories, all of which live in the gh-pages branch.
• When a tag of the form vX.Y.Z is pushed, publish the docs to the corresponding vX directory
• When code merges to main, publish docs to the canary directory