build_docs.yaml

name: Build and Deploy Docs

on:
  push:
    paths:
      - "doc/*.md"   # Trigger on changes to any markdown file
      - "**/*.py"   # Optionally include changes in Python files
    branches:
      - main        # Run the workflow only on pushes to the main branch
  workflow_dispatch:

# security: restrict permissions for CI jobs.
permissions:
  contents: read

jobs:
  build:
    name: Build Documentation
    runs-on: ubuntu-latest

    steps:
    - name: Checkout Code
      uses: actions/checkout@v4

    - name: Set up Micromamba
      uses: mamba-org/setup-micromamba@v2
      with:
        micromamba-version: "latest"       # Use the latest version of micromamba
        environment-file: .github/doc_env.yaml  # Reference your environment.yml file
        init-shell: bash
        cache-environment: true
        post-cleanup: 'all'
        # cache: true                        # Cache the micromamba environment

    - name: Install package
      # shell: bash -l {0}
      run: pip install -e .

    - name: Generate Documentation
      shell: bash -l {0} 
      run: pdoc synaptic_reconstruction -o doc/

    - name: Verify Documentation Output
      run: ls -la doc/

    - name: Upload Documentation Artifact
      uses: actions/upload-pages-artifact@v3
      with:
        # name: documentation
        path: doc/

  deploy:
    name: Deploy Documentation
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      # - name: Download Documentation Artifact
      #   uses: actions/download-artifact@v4
      #   with:
      #     name: documentation
      #     path: .

      - name: Deploy to GiHub Pages
        uses: actions/deploy-pages@v4
        # with: 
        #   artifact_name: documentation