Skip to content

Switch to using the deploy_sphinx_docs_multiversion action #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 23, 2025
Merged

Switch to using the deploy_sphinx_docs_multiversion action #78

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ac47811
switch to using the deploy_sphinx_docs_multiversion action
niksirbi Sep 23, 2025
f2d818b
make pre-commit happy
niksirbi Sep 23, 2025
67ee70e
tweak comment at the top of workflow
niksirbi Sep 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 29 additions & 152 deletions .github/workflows/docs_build_and_deploy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,21 @@
name: Build Sphinx docs and deploy to GitHub Pages

# Generate the documentation on all merges to main, all pull requests, or by
# manual workflow dispatch. The build job can be used as a CI check that the
# docs still build successfully. The deploy job only runs when a tag is pushed
# (so, when a new release is made).
# manual workflow dispatch from the main branch.
#
# The build job can be used as a CI check that the docs still build successfully.
#
# The deploy job runs under the following conditions:
# 1. When a tag is pushed (releases) the deploy job places the docs content on the
# gh-pages branch under a folder named after the release version (e.g. v0.3.0)
# and symlinks the "latest" version to it.
# 2. When a pull request is merged to main, or a workflow is manually dispatched from the main branch,
# the deploy job places the docs content on the gh-pages branch under a folder named "dev".
#
# Therefore, the "dev" folder always corresponds to the main branch on GitHub,
# whereas the "latest" folder corresponds to the most recent release.
# A version switcher dropdown enables switching between versions.

on:
push:
branches:
Expand All @@ -26,160 +38,25 @@ jobs:
needs: linting
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4

# Need the tags so that setuptools-scm can form a valid version number
- name: Fetch git tags
run: git fetch origin 'refs/tags/*:refs/tags/*'

- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: ${{ inputs.python-version }}

- name: Upgrade pip
shell: bash
run: |
# install pip=>20.1 to use "pip cache dir"
python3 -m pip install --upgrade pip

- name: Get pip cache dir
shell: bash
id: pip-cache
run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT

- name: Cache dependencies
uses: actions/cache@v4
with:
path: ${{ steps.pip-cache.outputs.dir }}
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-

- name: Install dependencies
shell: bash
run: python3 -m pip install -r ./docs/requirements.txt

- name: Check links
shell: bash
run: |
sphinx-build docs/source docs/build -b linkcheck

# needs to have sphinx.ext.githubpages in conf.py extensions list
- name: Building documentation
shell: bash
run: |
sphinx-build docs/source docs/build -b html -W --keep-going

- name: Upload the content for deployment
uses: actions/upload-artifact@v4
with:
name: docs-${{ github.sha }}
path: ./docs/build/
- uses: neuroinformatics-unit/actions/build_sphinx_docs@main
with:
check-links: true
use-make: false
fetch-tags: true

deploy_sphinx_docs:
name: Deploy Sphinx Docs
needs: build_sphinx_docs
runs-on: ubuntu-latest
permissions:
contents: write
if: github.event_name == 'push'
runs-on: ubuntu-latest
if: |
(github.event_name == 'push' && github.ref_type == 'tag') ||
(github.event_name == 'push' && github.ref == 'refs/heads/main') ||
(github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
steps:
- name: Checkout
uses: actions/checkout@v4

# Fetch the built docs from the "build_sphinx_docs" job
- name: Download HTML documentation artifact
uses: actions/download-artifact@v4
with:
name: docs-${{ github.sha }}
path: docs/build

- name: Checkout the gh-pages branch in a separate folder
uses: actions/checkout@v4
- uses: neuroinformatics-unit/actions/deploy_sphinx_docs_multiversion@main
with:
ref: gh-pages
# Checkout to this folder instead of the current one
path: deploy
# Download the entire history
fetch-depth: 0

- name: Push the built HTML to gh-pages
run: |
# Detect if this is a release or from the main branch
echo "Event name: ${{ github.event_name }}"
echo "Ref type: ${{ github.ref_type }}"
if [ "${{ github.event_name }}" = "push" ] && [ "${{ github.ref_type }}" = "tag" ]; then
# Get the tag name without the "refs/tags/" part
version="${GITHUB_REF#refs/*/}"
else
version=dev
fi
echo "Deploying version: $version"
# Make the new commit message. Needs to happen before cd into deploy
# to get the right commit hash.
message="Deploy $version from $(git rev-parse --short HEAD)"
cd deploy
# Need to have this file so that Github doesn't try to run Jekyll
touch .nojekyll
# Delete all the files and replace with our new set
echo -e "\nRemoving old files from previous builds of ${version}:"
rm -rvf ${version}
echo -e "\nCopying HTML files to ${version}:"
cp -Rvf ../docs/build ${version}/

if [[ "${version}" != "dev" ]]; then
# Updated switcher.json file
SWITCHER_CONTENT=$(curl https://neuroblueprint.neuroinformatics.dev/latest/_static/switcher.json)
BASE_URL="$(jq -r '.[1].url|split("/")[0:3]|join("/")' <<< $SWITCHER_CONTENT)"
NEW_URL="${BASE_URL}/latest/"
# Extract the current latest version entry
FIRST_ENTRY=$(jq '.[0]' <<< "${SWITCHER_CONTENT}")
CURRENT_LATEST_VERSION=$(echo $(jq '.[1].version' <<< "${SWITCHER_CONTENT}") | tr -d '"')

# Remove the "name" field from the current latest entry
UPDATED_CURRENT_LATEST_ENTRY=$(jq --arg url "${BASE_URL}/${CURRENT_LATEST_VERSION}" '.[1] | .url = $url | del(.name)' <<< "$SWITCHER_CONTENT")

# Create the new version entry with the "latest" tag
NEW_ENTRY=$(jq -n --arg version "${version}" --arg url "$NEW_URL" --arg name "$version (latest)" \
'{name: $name, version: $version, url: $url}')

# Combine the entries in the desired order
UPDATED_SWITCHER_CONTENT=$(jq --argjson first_entry "$FIRST_ENTRY" --argjson new_entry "$NEW_ENTRY" --argjson updated_current_latest "$UPDATED_CURRENT_LATEST_ENTRY" '[$first_entry, $new_entry, $updated_current_latest] + .[2:]' <<< "$SWITCHER_CONTENT")

SWITCHER_FILE="${version}/_static/switcher.json"
# Write the updated content back to switcher.json
echo "$UPDATED_SWITCHER_CONTENT" > "$SWITCHER_FILE"

echo "${version}/_static/switcher.json has been updated successfully."
fi

# If this is a new release, update the link from /latest to it
if [[ "${version}" != "dev" ]]; then
echo -e "\nSetup link from ${version} to 'latest'."
rm -f latest
ln -sf ${version} latest
fi
# Stage the commit
git add -A .
echo -e "\nChanges to be applied:"
git status
# Configure git to be the GitHub Actions account
git config user.email "github-actions[bot]@users.noreply.github.com"
git config user.name "github-actions[bot]"
# If this is a dev build and the last commit was from a dev build
# (detect if "dev" was in the previous commit message), reuse the
# same commit
if [[ "${version}" == "dev" && `git log -1 --format='%s'` == *"dev"* ]]; then
echo -e "\nAmending last commit:"
git commit --amend --reset-author -m "$message"
else
echo -e "\nMaking a new commit:"
git commit -m "$message"
fi
# Make the push quiet just in case there is anything that could leak
# sensitive information.
echo -e "\nPushing changes to gh-pages."
git push -fq origin gh-pages 2>&1 >/dev/null
echo -e "\nFinished uploading generated files."
secret_input: ${{ secrets.GITHUB_TOKEN }}
use-make: false
switcher-url: https://neuroblueprint.neuroinformatics.dev/latest/_static/switcher.json