docs.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

defaults:
  run:
    shell: bash -l {0}

jobs:

  docs:
    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@v2.0
      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
      id: deployment
      run: make -C docs html

    - name: Diagnostic
      run: ls -lAFgh docs/build/html
      # ${{ steps.deployment.outputs.artifact }}

    - name: Upload Docs ZIP file as artifact
      uses: actions/upload-artifact@v4
      with:
        name: gemviz-docs
        path: docs/build/html
        # ${{ steps.deployment.outputs.artifact }}
    
    - 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