docs.yaml

name: build docs

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
on:
  push:
    branches:
      - 'main'
      - 'release/*'
    tags:
      - 'v*'
  pull_request:
  merge_group:
    branches: ['main']

permissions:
  contents: read

jobs:
  builddocs:
    runs-on: ${{ matrix.os }}
    strategy:
      # don't stop other jobs if one fails
      # this is often due to network issues
      # and or flaky tests
      # and the time lost in such cases
      # is bigger than the gain from canceling the job
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        python-version: ["3.9", "3.10", "3.11", "3.12"]
        exclude:
          - os: windows-latest
            python-version: 3.9
          - os: windows-latest
            python-version: 3.10
          - os: windows-latest
            python-version: 3.11
    env:
      OS: ${{ matrix.os }}
      # The std-lib docstring of Int is not valid
      # causing errors like in the docstring of from_bytes (from Int)
      # WARNING: Inline interpreted text or phrase reference start-string without end-string.
      # when documenting subclasses of IntFlag such as in the lakeshore driver.
      # see https://github.com/python/cpython/pull/117847
      SPHINX_WARNINGS_AS_ERROR: false
      SPHINX_OPTS: "-v -j 2"
    steps:
    - name: Harden Runner
      uses: step-security/harden-runner@63c24ba6bd7ba022e95695ff85de572c04a18142 # v2.7.0
      with:
        egress-policy: audit
    - uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4.1.3
      with:
        # we need full history with tags for the version number
        fetch-depth: '0'
    - name: set-sphinx-opts
      run: |
        echo "SPHINX_OPTS=-W -v --keep-going -j 2" >> $GITHUB_ENV
      if: ${{ fromJSON(env.SPHINX_WARNINGS_AS_ERROR) }}
    - name: install pandoc linux
      run: |
        sudo apt update
        sudo apt install pandoc
      if: runner.os == 'Linux'
    - name: Install pandoc on windows
      uses: Wandalen/wretry.action@0dd1d5d77d019a6f85beb53d29e2ea2c7294d4f2 # v3.4.0
      with:
        action: crazy-max/ghaction-chocolatey@v1.6.0
        with: |
          args: install pandoc
        attempt_limit: 5
        attempt_delay: 1000
      if: runner.os == 'Windows'
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
      with:
        python-version: ${{ matrix.python-version }}
        cache: 'pip'
        cache-dependency-path: |
          pyproject.toml
          requirements.txt
          docs/conf.py
    - name: upgrade pip setuptools wheel
      run: python -m pip install --upgrade pip setuptools wheel
      shell: bash
    - name: install qcodes
      run: pip install -c requirements.txt .[docs]
    - name: Build docs on linux
      run: |
        cd docs
        export SPHINXOPTS="${{ env.SPHINX_OPTS }}"
        make html
      if: runner.os == 'Linux'
    - name: Build docs on windows
      run: |
        cd docs
        $env:SPHINXOPTS = "${{ env.SPHINX_OPTS }}"
        ./make.bat html
      if: runner.os == 'Windows'
    - name: Upload build docs
      uses: actions/upload-artifact@1746f4ab65b179e0ea60a494b83293b640dd5bba # v4.3.2
      with:
        name: docs_${{ matrix.python-version }}_${{ matrix.os }}
        path: ${{ github.workspace }}/docs/_build/html


  deploydocs:
    needs: builddocs
    runs-on: "ubuntu-latest"
    permissions:
      contents: write  # we need to be allowed to push to gh-pages
    if: ${{ github.ref == 'refs/heads/main' && github.event_name == 'push' }}
    steps:

    - name: Harden Runner
      uses: step-security/harden-runner@63c24ba6bd7ba022e95695ff85de572c04a18142 # v2.7.0
      with:
        egress-policy: audit

    - uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4.1.3

    - name: Download artifact
      uses: actions/download-artifact@8caf195ad4b1dee92908e23f56eeb0696f1dd42d # v4.1.5
      with:
        name: docs_3.11_ubuntu-latest
        path: build_docs

    - name: Deploy to gh pages
      uses: JamesIves/github-pages-deploy-action@ec9c88baef04b842ca6f0a132fd61c762aa6c1b0 # v4.6.0
      with:
        branch: gh-pages
        folder: ${{ github.workspace }}/build_docs/
        clean: true
        single-commit: true
        git-config-email: "bot"
        git-config-name: "Documentation Bot"