NeuroBlueprint/.github/workflows/docs_build_and_deploy.yml at main · neuroinformatics-unit/NeuroBlueprint · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
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 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:
      - 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: 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' && github.ref_type == 'tag') ||
      (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
      (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
    steps:
      - uses: neuroinformatics-unit/actions/deploy_sphinx_docs_multiversion@main
        with:
          secret_input: ${{ secrets.GITHUB_TOKEN }}
          use-make: false
          switcher-url: https://neuroblueprint.neuroinformatics.dev/latest/_static/switcher.json