documentation.yml

# This is a GitHub Actions workflow file 
# designed to automatically build and deploy Sphinx documentation to GitHub Pages.

# The name of the workflow as it appears in the GitHub Actions UI
name: documentation

# Defines the events that trigger this workflow: 
# Runs on code pushes, pull requests, and manual triggers (workflow_dispatch)
on: [push, pull_request, workflow_dispatch]

# Grants the workflow write permissions to the repository. 
# This is required so it can push the built HTML to the gh-pages branch later.
permissions:
  contents: write

jobs:
  docs:
    # Runs the job on a fresh Ubuntu Linux virtual machine hosted by GitHub
    runs-on: ubuntu-latest
    
    steps:
      # Step 1: Download your repository's code onto the runner so the workflow can use it
      - uses: actions/checkout@v6
      
      # Step 2: Install and set up a Python environment
      - uses: actions/setup-python@v6
      
      # Step 3: Install the required Python packages for building the docs
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r docs/requirements.txt        
          
      # Step 4: Run Sphinx to build the actual HTML documentation
      # This takes the source files from the 'docs' folder and outputs HTML to '_build'
      - name: Sphinx build
        run: |
          sphinx-build docs _build
          
      # Step 5: Deploy the built HTML files to a live GitHub Pages site
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        
        # Safety Check: ONLY run this deployment step if the workflow was triggered 
        # by a push to the main branch (prevents accidental deployments from PRs)
        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
        with:
          # Push the files to a branch specifically named 'gh-pages'
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          
          # Only upload the contents of the built HTML directory
          publish_dir: _build/
          
          # Keep the gh-pages branch history clean by wiping previous commits on that branch
          force_orphan: true