docs.yml

name: Documentation
on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'examples/**'
      - 'scripts/**'
      - 'mkdocs.yml'
      - '.github/workflows/docs.yml'

permissions:
  contents: write

jobs:
  docs:
    # Only run if commit message contains [build-docs]
    if: "contains(github.event.head_commit.message, '[build-docs]')"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # fetch all history for proper versioning

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e .[docs]

      # TODO: Enable this section when GPU runner is available
      # - name: Convert notebooks to markdown
      #   env:
      #     TESTING: "true"
      #     JUPYTER_CONFIG_DIR: "/tmp/jupyter-config"
      #   run: |
      #     # Convert notebooks to markdown
      #     jupyter nbconvert --to markdown examples/*.ipynb --output-dir docs/examples/ --TagRemovePreprocessor.remove_cell_tags hide
      #   # Note: This step requires GPU access. Currently notebooks should be converted locally
      #   # and committed to the repository. When setting up GPU runner:
      #   # 1. Use a runner with GPU support
      #   # 2. Add necessary CUDA dependencies
      #   # 3. Uncomment this section

      - name: Build script documentation
        run: |
          python docs/script_to_md.py

      - name: Deploy documentation
        run: |
          git config --global user.name "github-actions"
          git config --global user.email "github-actions@github.com"
          mkdocs gh-deploy --force