ci(build): preview PR builds via Read the Docs

[ReenigneArcher]

Description

Build PRs in Read the Docs as a way to preview builds before merging.

TODO:

• Test
• Document
• Get working in a re-usable easy to use way for other subprojects

Idea for getting GitHub artifacts to readthedocs

Warning

This is probably not a good idea as secrets cannot be protected in rtd for PRs. https://docs.readthedocs.com/platform/stable/guides/environment-variables.html

Suggest to set some environment variables in the readthedocs config for subprojects.

1. workflow name
2. artifact name
3. timeout in minutes, default to 10

Then get the sha from https://api.github.com/repos/{org}/{repo}/pulls/{pr number} at head.sha.

Then use the sha at https://api.github.com/repos/{org}/{repo}/commits/{sha}/check-runs and look for the matching workflow name, e.g. call-jekyll-build / Build Jekyll.

If the status is already completed move on. If not completed, then use a while loop and keep fetching https://api.github.com/repos/{org}/{repo}/check-runs/{run-id} until the status is completed or the timeout is reached. We also need to determine other possible statuses to watch for (possibly like cancelled, queued, etc.).

https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#list-workflow-run-artifacts

Must have "actions" scope to download an artifact. 😞

Edit: As a workaround to the requirement to use a github PAT, we can use nightly directly: e.g. https://nightly.link/LizardByte/Sunshine/actions/runs/13644059809/prep.zip 😃

Screenshot

Issues Fixed or Closed

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Dependency update (updates to dependencies)
• Documentation update (changes to documentation)
• Repository update (changes to repository files, e.g. .github/...)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated the in code docstring/documentation-blocks for new or existing methods/components

[Copilot]

PR Overview

This PR introduces a method to preview PR builds via Read the Docs by adding a Read the Docs configuration file, updating documentation with manual setup instructions, and enhancing the GitHub Actions workflow for Jekyll builds.

• Added a .readthedocs.yaml configuration file to define build settings for Read the Docs.
• Updated the README.md with detailed instructions and configuration examples for PR preview setup.
• Enhanced the extraction commands in the jekyll-build workflow by adding quotes for improved reliability.

Reviewed Changes

File	Description
.readthedocs.yaml	Adds Read the Docs configuration for project builds.
README.md	Introduces documentation for PR previews via Read the Docs.
.github/workflows/jekyll-build.yml	Improves command quoting for better shell command handling.

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.