Description

Refactored and better documented our CI workflows for generating documentation previews.

This PR needs to be merged before a follow-up which proposes to move away from the current pull_request + workflow_run approach that presently is not compatible with PRs from forks.

• If you would like to block and provide a review but lack time to do so within the next 24 hours, let me know otherwise I'm not expecting much feedback here and will merge without approval.
• I have ensured this change works as intended by testing via a separate repo of my own.

TL;DR: Overall, it's mostly shuffling stuff around, added comments and minor improvements. I wanted to keep the noise of these changes separate from the follow-up PR which will get a proper review process.

Overview of changes:

• Runner bumped from Ubuntu 22.04 => 24.04
• Revised inline documentation for maintainers.
• The output of build-docs.sh is now grouped in the steps action log, and now hides the noise from pulling the image via docker run.
• Removed the separate tar steps with ZSTD:
  • There is now only a single directory to archive since recent changes to this workflow (removal of pr.env). The upload + download actions are sufficient enough for a zip archive.
  • NOTE: For context, in the past dawidd6/action-download-artifact was used because actions/download-artifact did not support retrieving the workflow.
• The workflow_run job has had the PR context restore step extracted to a separate job to minimize noise.
• actions-netlify is still effectively the same functionality.
  • github-token is no longer configured as it doesn't appear needed with the functions disabled.
  • Opt-out of the GH deployments feature which is not needed.

NOTE: The current workflow_run (master) is expected to fail due to the pull_request (prepare) workflow running from this PR instead of the master branch version of the workflow. Failure is due to change in artifact upload/download.

Type of change

• Improvement (non-breaking change that does improve existing functionality)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• New and existing unit tests pass locally with my changes