docs.yml

name: documentation builds
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
on:
  push:
    branches:
      - master
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
  release:
    types:
      - created
  schedule:
    - cron: '0 6 * * 1'
  workflow_dispatch:
    inputs:
      nb_execution_mode:
        description: 'run notebooks (force/off)'
        required: true
        default: 'force'
      upload_docs:
        description: 'upload docs as artifacts'
        type: boolean
        required: false
        default: false

# execute commands with conda aware shell by default:
defaults:
  run:
    shell: bash -el {0}

jobs:
  build:
    if: |
      (github.event.pull_request.draft == false) ||
      (github.event_name == 'workflow_dispatch') ||
      (github.ref == 'refs/heads/master')
    name: sphinx build
    runs-on: ubuntu-latest
    env:
      nb_execution_mode: 'force'
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history for all tags and branches

      - name: Setup Conda Environment
        uses: mamba-org/setup-micromamba@v2.0.3
        with:
          environment-file: ./doc/rtd_environment.yml
          environment-name: rtd
          init-shell: >-
            bash
            powershell
          cache-environment: false

      - name: activate build env
        run: micromamba activate rtd

      - name: conda info
        run: conda info

      - name: conda list
        run: conda list

      - name: install weldx kernel
        run: ipython kernel install --user --name=weldx

      - name: set notebook execution
        if: (github.event_name == 'workflow_dispatch')
        run: echo "nb_execution_mode=${{ github.event.inputs.nb_execution_mode }}" >> $GITHUB_ENV

      - name: Build docs
        run: sphinx-build -W -n -b html -d build/doctrees doc/src build/html --keep-going -j 2 -D nb_execution_mode=${{ env.nb_execution_mode }}

      - uses: actions/upload-artifact@v4
        if: |
          always() && (
          startsWith(github.ref, 'refs/tags/') ||
          ((github.event_name == 'workflow_dispatch') && (github.event.inputs.upload_docs == 'true')) ||
          (github.ref == 'refs/heads/master') ||
          (github.event_name == 'release' && github.event.action == 'created')
          )
        with:
          name: weldx-docs
          path: build/html