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

Author: ReenigneArcher

.readthedocs.yaml

@@ -0,0 +1,18 @@
+---
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    ruby: "3.3"
+  commands:
+    - |
+      chmod +x "./scripts/readthedocs_build.sh"
+      "./scripts/readthedocs_build.sh"
+
+submodules:
+  include: all
+  recursive: true

README.md

@@ -66,3 +66,34 @@ jobs:
 ```
 
 For additional options see [jekyll-build.yml](.github/workflows/jekyll-build.yml)
+
+### PR Previews
+
+Changes to gh-pages can be previewed, by setting up the project in ReadTheDocs.
+It is recommended to use the following manual configuration:
+
+Initial setup:
+```yml
+Name: LizardByte-gh-pages-<repo_name>  # the project slug cannot be changed after creation
+Repository URL: https://github.com/LizardByte/<repo_name>.git
+Default-branch: master
+Language: English
+```
+
+Project Settings:
+```yml
+Connected-repository: https://github.com/LizardByte/<repo_name>.git
+URL-versioning-scheme: Multiple versions without translations
+Path-for-.readthedocs.yaml:  # only set if not in the root of the repo
+Programming-Language: Other
+Project-homepage: https://app.lizardbyte.dev/<repo_name>
+Description: Preview PRs for gh-pages
+Build-pull-requests-for-this-project: true
+```
+
+Additionally, do the following:
+
+1. Deactivate the `stable` version
+2. Make the `latest` version hidden
+3. Add project as a subproject of `LizardByte-gh-pages-main`
+4. Update branch protection rules in GitHub repo settings to require status checks from ReadTheDocs

scripts/readthedocs_build.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+set -e
+
+# set default directories
+project_dir="."
+theme_dir="."
+
+# TODO: make this work for subproject gh-pages
+# if not the theme project then we need to clone the theme with submodules
+if [ "$READTHEDOCS_PROJECT" != "lizardbytegithubio" ]; then
+  theme_dir="theme"
+  git clone --depth 1 https://github.com/LizardByte/LizardByte.github.io.git ${theme_dir} --recurse-submodules
+fi
+
+TMPDIR=$(pwd)/../tmp
+mkdir -p ${TMPDIR}
+
+base_dirs=(
+    ${theme_dir}/third-party/beautiful-jekyll
+    ${theme_dir}
+)
+
+targets=(
+  *.gemspec
+  _data
+  _includes
+  _layouts
+  _sass
+  assets
+  404.html
+  _config_theme.yml
+  favicon.ico
+  feed.xml
+  Gemfile
+  staticman.yml
+  tags.html
+)
+
+for base_dir in "${base_dirs[@]}"; do
+  for target in "${targets[@]}"; do
+    if [ -e "$base_dir/$target" ]; then
+      cp -rf "$base_dir/$target" ${TMPDIR}/
+    fi
+  done
+done
+
+# copy project directory, they should only come from the project repo
+cp -RTf ${project_dir}/ ${TMPDIR}/
+
+cd ${TMPDIR}
+
+gem install bundle
+bundle install
+echo "baseurl: $READTHEDOCS_VERSION" > _config_rtd.yml
+cat _config_rtd.yml
+cat _config_theme.yml
+bundle exec jekyll build \
+  --future \
+  --config _config_rtd.yml,_config_theme.yml \
+  --destination $READTHEDOCS_OUTPUT/html
+ls -Ra $READTHEDOCS_OUTPUT