docs_build_and_deploy.yml

name: Docs

# 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 and actually moves the generated html to the gh-pages branch
# (which triggers a GitHub pages deployment).
on:
  push:
    branches:
      - main
    tags:
      - '*'
  pull_request:
  merge_group:
  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
    runs-on: ubuntu-latest
    steps:
      - uses: neuroinformatics-unit/actions/build_sphinx_docs@main
        with:
          python-version: 3.11
          use-make: true

  deploy_sphinx_docs:
    name: Deploy Sphinx Docs
    needs: build_sphinx_docs
    permissions:
      contents: write
    if: (github.event_name == 'push' && github.ref_type == 'tag') || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    steps:
      - uses: neuroinformatics-unit/actions/deploy_sphinx_docs@main
        with:
          secret_input: ${{ secrets.GITHUB_TOKEN }}
          use-make: true