Skip to content

[docs] Rewrite URLs in Markdown files for docs previews (#295) #3

[docs] Rewrite URLs in Markdown files for docs previews (#295)

[docs] Rewrite URLs in Markdown files for docs previews (#295) #3

Workflow file for this run

name: Publish docs via GitHub Pages
on:
push:
branches:
- main
paths:
- 'mkdocs.yml'
- '.github/workflows/docs.yml'
- 'docs/**'
- 'benchmarks/**/*.md'
- 'post-processing/**/*.md'
pull_request:
branches:
- main
paths:
- 'mkdocs.yml'
- '.github/workflows/docs.yml'
- 'docs/**'
- 'benchmarks/**/*.md'
- 'post-processing/**/*.md'
concurrency:
# Same group concurrency as the `docs_cleanup.yml` workflow, because they both
# git-push to the same branch, so we want to avoid clashes. NOTE: this is
# different from the concurrency group below, which is to cancel successive
# jobs from within the branch/PR.
group: docs-pushing
jobs:
build:
timeout-minutes: 10
name: Deploy docs
runs-on: ubuntu-latest
concurrency:
# Skip intermediate builds: always.
# Cancel intermediate builds: always.
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
permissions:
# See
# <https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token>.
# We need `contents: write` to push the docs to the `gh-pages` branch, and
# `statuses: write` to create the custom status.
contents: write
statuses: write
steps:
- name: Checkout main
uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.10.6'
cache: 'pip'
- name: Install Python dependencies
run: pip install mkdocs-material github3.py
- name: Checkout gh-pages
uses: actions/checkout@v4
with:
ref: gh-pages
path: gh-pages
- name: Cleanup unrelated files
run: |
# Under `apps` we want to keep only the `README.md` files. All other files
# (reframe tests, input files, etc...) should be ignored by the docs.
find benchmarks/apps -type f \! \( -name 'README.md' \) -print -delete
- name: Rewrite URLs in Markdown files for previews
# Run only if this is a PR for which we're going to deploy the preview.
if: ${{ github.event_name == 'pull_request' && ! github.event.pull_request.head.repo.fork }}
run: |
BASE_URL="https://ukri-excalibur.github.io/excalibur-tests"
echo "BASE_URL=${BASE_URL}" >> "${GITHUB_ENV}"
PREVIEW_SUBDIR="preview/PR${{ github.event.number }}"
echo "PREVIEW_SUBDIR=${PREVIEW_SUBDIR}" >> "${GITHUB_ENV}"
find . -name '*.md' -print -exec sed -i "s|${BASE_URL}|${BASE_URL}/${PREVIEW_SUBDIR}|g" '{}' \;
- name: Build docs
run: |
if [[ ${{ github.event_name }} == 'pull_request' ]]; then
export MKDOCS_SITE_DIR="site/${PREVIEW_SUBDIR}"
export MKDOCS_SITE_URL="${BASE_URL}/${PREVIEW_SUBDIR}"
fi
mkdocs build
- name: Deploy docs
# Run only if push is to `main`, or if it's a PR not from a fork.
if: ${{ (github.event_name == 'push' && github.ref == 'refs/heads/main') || (github.event_name == 'pull_request' && ! github.event.pull_request.head.repo.fork) }}
working-directory: gh-pages
run: |
git config user.name ${{github.actor}}
git config user.email "${{github.actor_id}}+${{github.actor}}@users.noreply.github.com"
# Before copying the new files, delete the old ones, so that we can
# cleanly update the website.
if [[ ${{ github.event_name }} == 'pull_request' ]]; then
COMMIT_MESSAGE="Update docs preview from ${{ github.sha }}"
# Only delete files in the preview subdir, if any
if [[ -d "${PREVIEW_SUBDIR}" ]]; then
git rm -rf "${PREVIEW_SUBDIR}"
fi
else
COMMIT_MESSAGE="Update docs from ${{ github.sha }}"
for file in $(git ls-files); do
if [[ x"${file}" != xpreview/* ]]; then
# Do not delete files in the `preview/` subdir
git rm ${file}
fi
done
fi
cp -fr ../site/* .
git add .
git commit -m "${COMMIT_MESSAGE}"
git push origin gh-pages
- name: Create custom status for pull requests
# Similar condition as previous step, but only for PRs
if: ${{ github.event_name == 'pull_request' && ! github.event.pull_request.head.repo.fork }}
shell: python {0}
run: |
import os
from github3 import login
token = "${{ github.token }}"
gh = login(token=token)
owner, repo_name = "${{ github.repository }}".split('/')
repo = gh.repository(owner, repo_name)
sha = "${{ github.event.pull_request.head.sha }}"
state = "success"
base_url = os.getenv("BASE_URL")
preview_subdir = os.getenv("PREVIEW_SUBDIR")
target_url = f"{base_url}/{preview_subdir}/"
description = "Documentation deployed"
context = "${{ github.workflow }} / Preview"
repo.create_status(sha, state, target_url, description, context)