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.10", "3.11", "3.12"]
        exclude:
          - os: windows-latest
            python-version: 3.10
          - os: windows-latest
            python-version: 3.11
    env:
      OS: ${{ matrix.os }}
      SPHINX_WARNINGS_AS_ERROR: true
      SPHINX_OPTS: "-v -j 2"
    steps:
    - name: Harden Runner
      uses: step-security/harden-runner@5c7944e73c4c2a096b17a9cb74d65b6c2bbafbde # v2.9.1
      with:
        egress-policy: audit
    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
      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
    # add the || true logic to not error in case the index cannot be fetched.
    # this is known to have happened before e.g.
    # https://github.com/microsoft/linux-package-repositories/issues/130
      run: |
        sudo apt update || true
        sudo apt install pandoc
      if: runner.os == 'Linux'
    - name: Install pandoc on windows
      uses: Wandalen/wretry.action@6feedb7dedadeb826de0f45ff482b53b379a7844 # v3.5.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@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.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@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
      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@5c7944e73c4c2a096b17a9cb74d65b6c2bbafbde # v2.9.1
      with:
        egress-policy: audit

    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7

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

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