pages.yml

name: Publish Sphinx Docs to GitHub Pages

on:
  # Build the docs on pushes to main branch, PRs to main branch, and new tags.
  # Publish only on demand.
  push:
    branches:
      - main
    tags:
      - '*'  # all tags
  pull_request:
    branches:
      - main
  workflow_dispatch:   # allow manual triggering
    inputs:
      deploy:
        description: 'Deploy documentation'
        type: boolean
        required: true
        default: false

jobs:

  pages:
    runs-on: ubuntu-latest

    steps:

    - name: Deploy Information
      if: ${{ github.event.inputs.deploy }}
      run: echo "The docs will be published from this workflow run."

    - name: Set timezone
      uses: szenius/set-timezone@v1.2
      with:
        timezoneLinux: "America/Chicago"

    - name: Checkout
      uses: actions/checkout@v4
      with:
        fetch-depth: 0 # otherwise, you will failed to push refs to dest repo

    - uses: actions/setup-python@v5
      with:
        python-version: "3.11"

    - name: Install Sphinx build requirements
      run: pip install -r ./docs/requirements.txt

    - name: Install our package
      run: pip install --no-deps -e . -vv

    - name: Sphinx
      run: make -C docs html

    - name: Publish (push gh-pages branch) only on demand
      uses: peaceiris/actions-gh-pages@v4
      if: ${{ github.event.inputs.deploy }}
      with:
        publish_branch: gh-pages
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/build/html
        force_orphan: true