Automate documentation building

[mdickinson]

This PR automates documentation building for the Envisage repository. It repurposes the current structure of the gh-pages branch, and adds workflows for updating documentation on every push to main and every release.

New gh-pages structure

The new gh-pages structure is as follows:

• The top-level directory contains documentation that matches the current in-development version of the codebase.
• The <major>.<minor> numbered subdirectories (5.2, 6.0, 6.1, etc.) contain documentation for released versions of Envisage

Note: as before, documentation for a bugfix release (e.g., Envisage 7.1.1) overwrites the documentation for the previous release (e.g., Envisage 7.1.0). This is deliberate - documentation bugs may be fixed in a bugfix release, but it should be rare for an API to change in a bugfix release, and for any given <major>.<minor> version number users should usually be seeing the latest documentation.

Workflows

This PR adds two workflows for updating the docs:

• The update-gh-pages.yml workflow updates the in-development docs on every push to the main branch (i.e., every PR merge)
• The update-gh-pages-on-release.yml workflow updates the release docs on every published release.

Both workflows use the new graft_docs.py script to do the work of copying the newly-built docs to the appropriate place in the gh-pages branch.

The workflows are very similar: the key differences between the two workflows are the triggers, and the passing of the --tag argument to graft_docs.py in the release case. Otherwise, the workflows are essentially identical.

Notes

I've created a branch gh-pages-staging for testing purposes; both workflows are currently pushing changes to that branch instead of gh-pages. When we're happy that this PR is working as intended, we should replace gh-pages-staging with gh-pages throughout. At the same time, we'll need to remove branch protections on the gh-pages branch.

To do after PR approval and prior to merge:

• [x] Replace gh-pages-staging with gh-pages throughout
• [x] Remove branch protections on gh-pages, so that we can push to it

[mdickinson]

A couple of notes from an internal discussion:

• It would be useful to have a top-level symlink (name? "latest"? "current"?) that always points to the latest release; I think it would be reasonably easy to update graft_docs.py to maintain that.
• It's a bit ugly that graft_docs.py lives at the top level of the repository. We could move both it and etstool.py to a new ci subdirectory. That would probably best be done in a separate PR, since it'll involve changing a good number of files (other workflows, README instructions, etc.) I considered moving it into .github, but it's not really specific to the GitHub workflows, even though it's used by them.

[mdickinson]

And two more thoughts:

• graft_docs.py should be renamed to something that clearly indicates it's related to maintaining the gh-pages documentation.
• How about the docs/ directory as a home for graft_docs.py? We're already putting the documentation requirements file there.

[mdickinson]

I've updated the branch protections for the gh-pages branch to something that'll allow the workflows to push commits, but that should still protect us from accidental changes.

• Clear the "Require a pull request before merging" option; no PRs required
• Set the "Require linear history" option - this should help protect us from possible race conditions if two PRs are merged in quick succession. In those situations (which should I hope be rare), a manual run should ensure that everything's up to date.
• Do not "Allow force pushes"
• Do not "Allow deletions"

[mdickinson]

@corranwebster Thanks for review!

[...] we probably need to start enforcing that the docs build cleanly in every PR [...]

Yep, the test-doc-build.yml workflow already does this for PR commits. The duplication between that and the two workflows in this PR is a little bit of a DRY violation, and could potentially be pulled out into a composite action.

[...] about the usefulness of having a "release"/"stable" or similar symlink [...]

I've updated this PR to add a "latest" symlink in 6677787f1c1cddda9c270a1e59c1a54fd0de63e0.

Do we want info@enthought.com here?

Sure, why not. Done in 2c7ab646a16795c3b464ae8ea0e53b91ae617f6b.

[mdickinson]

How about the docs/ directory as a home for graft_docs.py?

Done in fa666d083fadaed541a285f5d6be15c819e58d43

[mdickinson]

And apparently I managed to introduce a syntax error into the workflow the moment I stopped testing. Fixed in ebc60f9d6d0b3b628cbafeab7f925d92f62affc8.