Add workflow for multi-version sphinx docs #72
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: | |
| - 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' && github.ref_type == 'tag' | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: neuroinformatics-unit/actions/deploy_sphinx_docs@v2 | |
| with: | |
| secret_input: ${{ secrets.GITHUB_TOKEN }} |