Add workflow for multi-version sphinx docs #103
Workflow file for this run
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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). | |
| on: | |
| push: | |
| branches: | |
| - main | |
| tags: | |
| - '*' | |
| pull_request: | |
| workflow_dispatch: | |
| jobs: | |
| linting: | |
| # scheduled workflows should not run on forks | |
| if: (${{ github.event_name == 'schedule' }} && ${{ github.repository_owner == 'neuroinformatics-unit' }} && ${{ github.ref == 'refs/heads/main' }}) || (${{ github.event_name != 'schedule' }}) | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: neuroinformatics-unit/actions/lint@v2 | |
| build_sphinx_docs: | |
| name: Build Sphinx Docs | |
| 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/ | |
| deploy_sphinx_docs: | |
| name: Deploy Sphinx Docs | |
| needs: build_sphinx_docs | |
| permissions: | |
| contents: write | |
| if: github.event_name == 'push' | |
| runs-on: ubuntu-latest | |
| 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-test branch in a separate folder | |
| uses: actions/checkout@v4 | |
| with: | |
| ref: gh-pages-test | |
| # 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-test | |
| 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_FILE="${version}/_static/switcher.json" | |
| SWITCHER_CONTENT=$(cat "${SWITCHER_FILE}") | |
| BASE_URL="$(jq -r '.[1].url|split("/")[0:3]|join("/")' $SWITCHER_FILE)" | |
| NEW_URL="${BASE_URL}/stable/" | |
| # 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 "stable" tag | |
| NEW_ENTRY=$(jq -n --arg version "${version}" --arg url "$NEW_URL" --arg name "$version (stable)" \ | |
| '{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_stable "$UPDATED_CURRENT_LATEST_ENTRY" '[$first_entry, $new_entry, $updated_current_stable] + .[2:]' <<< "$SWITCHER_CONTENT") | |
| # Write the updated content back to switcher.json | |
| echo "$UPDATED_SWITCHER_CONTENT" > "$SWITCHER_FILE" | |
| echo "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-test." | |
| git push -fq origin gh-pages-test 2>&1 >/dev/null | |
| echo -e "\nFinished uploading generated files." |