mims-harvard__tooluniverse/.github/workflows/deploy-docs.yml

name: Deploy ToolUniverse Documentation

on:
  push:
    branches: [main, master]
    paths:
      - 'docs/**'
      - 'src/**'
      - 'skills/**'
      - 'pyproject.toml'
      - '.github/workflows/deploy-docs.yml'
  workflow_dispatch:

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

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4
      with:
        fetch-depth: 1  # Shallow clone for faster checkout
      
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.11'
        cache: 'pip'
        
    - name: Cache Sphinx build
      uses: actions/cache@v4
      with:
        path: |
          docs/_build/doctrees
          docs/api
        key: sphinx-${{ runner.os }}-${{ hashFiles('docs/**/*.rst', 'docs/**/*.py', 'src/**/*.py', 'pyproject.toml') }}
        restore-keys: |
          sphinx-${{ runner.os }}-
        
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip uv
        # Install project with docs extras (includes all documentation dependencies)
        uv pip install --system -e .[docs]
        # Install additional requirements from docs/requirements.txt
        pip install -r docs/requirements.txt
        
    - name: Verify documentation setup
      run: |
        echo "🔍 Verifying Sphinx and theme installation..."
        python -c "import sphinx; print(f'✅ Sphinx {sphinx.__version__}')"
        python -c "import furo; print('✅ Furo theme available')" || echo "⚠️ Furo theme not available"
        python -c "import pydata_sphinx_theme; print('✅ PyData theme available')" || echo "⚠️ PyData theme not available"
        python -c "import sphinx_rtd_theme; print('✅ RTD theme available')" || echo "⚠️ RTD theme not available"
        python -c "import shibuya; print('✅ Shibuya theme available')" || echo "⚠️ Shibuya theme not available"
        python -c "from linkify_it import LinkifyIt; print('✅ Linkify available')"
        python -c "import myst_parser; print('✅ MyST parser available')"
        python -c "import sphinx_design; print('✅ Sphinx Design available')"
        python -c "import sphinx_copybutton; print('✅ Sphinx Copybutton available')"
        python -c "import sphinx_tabs; print('✅ Sphinx Tabs available')"
        
    - name: Prepare assets
      run: |
        cd docs
        mkdir -p _static
        if [ -f "../img/tooluniverse_logo.png" ]; then
          cp ../img/tooluniverse_logo.png _static/
          echo "✅ Logo prepared"
        fi
        
    - name: Regenerate tool and skills documentation
      run: |
        cd docs
        echo "🔧 Regenerating tool reference documentation..."
        python generate_config_index.py || echo "⚠️ generate_config_index.py not found or failed"
        python generate_remote_tools_docs.py || echo "⚠️ generate_remote_tools_docs.py not found or failed"
        python generate_tool_reference.py || echo "⚠️ generate_tool_reference.py not found or failed"
        echo "✨ Regenerating skills showcase documentation..."
        python generate_skills_showcase.py || echo "⚠️ generate_skills_showcase.py not found or failed"
        echo "✅ Documentation regeneration complete"
        
    - name: Build documentation
      run: |
        cd docs
        # Skip dependency installation in script (already done above)
        # Use optimized API doc generation settings
        echo "🔨 Building documentation with optimized settings..."
        DOC_LANGUAGES="en,zh_CN" \
        DOC_SKIP_SERVER_PROMPT=1 \
        DOC_SKIP_INSTALL=1 \
        DOC_OPTIMIZED=1 \
        ./quick_doc_build.sh
        
    - name: Check build output
      run: |
        if [ ! -f docs/_build/html/index.html ]; then
          echo "❌ Root index.html not found!"
          exit 1
        fi
        echo "✅ Documentation built successfully"
        du -sh docs/_build/html
        
    - name: Add .nojekyll file
      run: |
        touch docs/_build/html/.nojekyll
        
    # Note: Do NOT create a CNAME here. This project is served under
    # https://zitniklab.hms.harvard.edu/ToolUniverse/.
    # Adding a CNAME would incorrectly claim the root domain.
        
    - name: Setup Pages
      uses: actions/configure-pages@v4
      
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v3
      with:
        path: './docs/_build/html'
        
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4