docs.yml

name: Build and Deploy Documentation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Setup Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.9'

    - name: Cache pip dependencies
      uses: actions/cache@v3
      with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', '**/pyproject.toml') }}
        restore-keys: |
          ${{ runner.os }}-pip-

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        # Install basic dependencies for documentation
        pip install sphinx sphinx-autodoc-typehints sphinx-rtd-theme
        pip install numpy pandas matplotlib tqdm h5py
        # Install torch and torch-geometric (CPU versions for docs)
        pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
        pip install torch-geometric
        # Try to install project dependencies if they exist
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
        if [ -f pyproject.toml ]; then pip install -e .; fi

    - name: Setup Sphinx documentation
      run: |
        # Create docs directory if it doesn't exist
        mkdir -p docs
        cd docs
        
        # Initialize Sphinx if not already done
        if [ ! -f conf.py ]; then
          sphinx-quickstart --quiet --sep --project "FoldTree2" \
            --author "DessimozLab" --release "1.0" --language en \
            --extensions sphinx.ext.autodoc,sphinx.ext.viewcode,sphinx.ext.napoleon \
            --makefile --no-batchfile .
        fi

    - name: Configure Sphinx
      run: |
        cd docs
        # Create or update conf.py with proper configuration
        cat > conf.py << 'EOF'
        import os
        import sys
        sys.path.insert(0, os.path.abspath('..'))

        project = 'FoldTree2'
        copyright = '2025, DessimozLab'
        author = 'DessimozLab'
        release = '1.0'

        extensions = [
            'sphinx.ext.autodoc',
            'sphinx.ext.viewcode',
            'sphinx.ext.napoleon',
            'sphinx.ext.githubpages',
        ]

        templates_path = ['_templates']
        exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

        html_theme = 'sphinx_rtd_theme'
        html_static_path = ['_static']

        # Napoleon settings for Google/NumPy style docstrings
        napoleon_google_docstring = True
        napoleon_numpy_docstring = True
        napoleon_include_init_with_doc = False
        napoleon_include_private_with_doc = False

        # Autodoc settings
        autodoc_default_options = {
            'members': True,
            'undoc-members': True,
            'show-inheritance': True,
        }
        EOF

    - name: Generate API documentation
      run: |
        cd docs
        # Create index.rst if it doesn't exist
        cat > index.rst << 'EOF'
        FoldTree2 Documentation
        =======================

        FoldTree2 is a toolkit for protein structure phylogenetic analysis using neural network encoders.

        .. toctree::
           :maxdepth: 2
           :caption: Contents:

           modules

        Overview
        --------

        FoldTree2 combines structural biology and phylogenetics by:

        * Encoding protein structures using trained neural networks
        * Generating structure-based substitution matrices
        * Performing phylogenetic inference with structural information

        API Reference
        =============

        .. toctree::
           :maxdepth: 4

           foldtree2

        Indices and tables
        ==================

        * :ref:`genindex`
        * :ref:`modindex`
        * :ref:`search`
        EOF

        # Generate module documentation
        sphinx-apidoc -f -o . ../foldtree2 --separate

    - name: Build documentation
      run: |
        cd docs
        make html

    - name: Setup Pages
      uses: actions/configure-pages@v3

    - name: Upload artifact
      uses: actions/upload-pages-artifact@v2
      with:
        path: './docs/_build/html'

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/main'
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2