docs.yaml

name: Build and Publish Docs

permissions:
  contents: write
  pages: write
  id-token: write

on:
  release:
    types: [published]

jobs:
  build-docs:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest]
        python-version: ['3.10']
        include:
        - os: ubuntu-latest
          python-version: '3.10'
          deploy: true   # Only deploy from this configuration
    outputs:
      deploy: ${{ steps.set-deploy-output.outputs.deploy }}
    steps:
    - uses: actions/checkout@v4
      with: # no need for the history
        fetch-depth: 0
    - uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.python-version }}
    # Cache Poetry dependencies to speed up builds
    - name: Cache Poetry virtualenv
      uses: actions/cache@v3
      with:
        path: ~/.cache/pypoetry
        key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
        restore-keys: |
          ${{ runner.os }}-poetry-
    - name: Install dependencies
      run: |
        python -m pip install poetry
        poetry install --with docs
      shell: bash
    - name: Build docs
      run: |
        poetry run pdoc . -o docs -t docs_style/pdoc-theme --docformat google
        touch docs/.nojekyll
      shell: bash
    - name: Determine if deployment is needed
      id: set-deploy-output
      run: echo "::set-output name=deploy::true"
      shell: bash
    - uses: actions/upload-artifact@v3
      with:
        name: documentation
        path: docs

  publish-docs:
    needs: build-docs
    if: ${{ needs.build-docs.outputs.deploy == 'true' }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest] # For demonstration, other OSes are commented out
        python-version: ['3.10']
        include:
        - os: ubuntu-latest
          python-version: '3.10'
          deploy: true   # Only deploy from this configuration
    steps:
    - uses: actions/checkout@v4
    - uses: actions/download-artifact@v3
      with:
        name: documentation
        path: docs
    - uses: JamesIves/github-pages-deploy-action@v4
      with:
        folder: docs
        branch: docs