docs.yml

# Sphinx docs check
# -----------------
#
# There are 2 main reasons for having this dedicated Sphinx docs check in
# addition to the Read the Docs (RTD) builder:
#
# 1. This action is set up to fail on Sphinx warnings, whereas RTD's will show
# a passing sign for warnings, and only fail for errors. So this is a stricter
# check.
#
# 2. When this action detects warnings, it produces GitHub annotations on the
# Files Changed tab in the pull request. Such annotations can be convenient for
# developers/code reviewers (e.g., the same way CodeCov and CodeFactor
# annotate).
# -----------------

name: "Documentation check"
on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - ready_for_review

permissions: write-all

jobs:
  determine_runner:
    if: github.event.pull_request.draft == false
    name: Determine runner type to use
    uses: ./.github/workflows/determine-workflow-runner.yml
    with:
      default_runner: ubuntu-latest

  sphinx:
    if: github.event.pull_request.draft == false
    needs: [determine_runner]
    runs-on: ${{ needs.determine_runner.outputs.runner_group }}
    steps:
    - uses: actions/checkout@v4
    - uses: PennyLaneAI/sphinx-action@master
      with:
        docs-folder: "doc/"
        pre-build-command: >
            apt install -y graphviz
            && pip3 install -r doc/requirements.txt
            && pip3 install .
            && pip3 install openfermionpyscf
            && pip3 install aiohttp fsspec h5py
        build-command: "sphinx-build -b html . _build -W --keep-going"

    - name: Freeze dependencies
      shell: bash
      run: |
        pip freeze | grep -v 'file:///' > doc.txt
        cat doc.txt

    - name: Upload frozen requirements
      uses: actions/upload-artifact@v4
      with:
        name: frozen-doc
        path: doc.txt

  upload-stable-deps:
    if: github.event.pull_request.draft == false
    needs:
      - determine_runner
      - sphinx
    uses: ./.github/workflows/check_in_artifact.yml
    with:
      artifact_name_pattern: "frozen-doc"
      artifact_save_path: ".github/stable/"
      merge_multiple: true
      pull_request_head_branch_name: bot/stable-deps-update
      commit_message_description: Frozen Doc Dependencies Update
      pull_request_title: Update stable dependency files
      pull_request_body: |
        Automatic update of stable requirement files to snapshot valid python environments.