Update to modern GitHub Pages deployment

[bparks13]

This PR updates the GitHub actions to use the modern GitHub pages deployment, instead of using a gh-pages branch. These changes are based on actions utilized in other Sphinx documentation builds.

There are also changes to the actions that check all links, ensuring that they are valid. This step requires some changes to existing pages, to remove duplicate anchors and to fix broken links.

The way this PR changes the actions workflow assumes several things which are not currently true in this repo. I will provide a brief description of what is expected, and we can determine how much or how little we implement here.

Potential new workflow

1. A ruleset is implemented for this repo that prevents directly pushing to the main branch
2. Due to 1), all changes must be implemented by creating a new branch and opening a PR
3. Once a PR is opened, the actions will automatically run to perform the following steps:
   • Build all documentation. This step can fail if there are errors during the build process, which the ruleset from 1) will then prevent this PR from being merged into main
   • Check all links and anchors in all files. This step can fail if a link is now broken, or if an anchor name was changed and now the ref is no longer valid. Again, this would prevent the PR from being merged
   • Upload a GitHub Pages artifact to the workflow, allowing anyone with access to the actions the ability to download the full compiled HTML pages in a zip folder for testing locally without the need to build the documentation from scratch. NOTE: this does not publish these pages to the actual website yet, it only saves them inside of the Actions tab.
     • Additional note: The format is saved as an artifact.tar, which requires additional steps to unpack before it can be viewed locally. We can provide documentation on how to do this in the README, so that it is easier to distribute previews of the docs if needed
4. If everything runs successfully, then the PR is able to be merged
   • In other repos, we also have it set so that at least one person must review the code before it can be merged. Depending on how the current workflow is set up, we can either implement or skip this option
5. Once the PR is merged to main, the action will run again, and perform the exact same steps (build / test documentation and links, upload artifact). Now, there will be a second stage of the action that runs, which will upload the Pages artifact so that it now is publicly availably on the website
   • This step requires a small adjustment to the settings, specifying that the website is now being delivered by an action instead of from the gh-pages branch, but there is no difference from the end user perspective

[jsiegle]

Is it expected that the build will fail before the changes are merged? If so, this looks good!

[bparks13]

@jsiegle No, the build should succeed, I just pushed the changes to make sure that the actions were running correctly and would fail if the checks didn't pass. Now that I've updated the links and the sphinx version it should always succeed. If this format is acceptable, I can take care of modifying the repos settings based on feedback. I have updated the PR comments to include more details on how the workflow is set up for other documentation repos, and we can decide how much we want to do here.

[jsiegle]

Ok, great! Let's make it so at least one review is required for now, and if it becomes to cumbersome we can disable this.