documentation.yml

name: Build docs

# Runs on pushes targeting the default branch
on:
  push:
    branches:
    - main
  pull_request:
    branches:
    - main

# Cancel in-progress runs when pushing a new commit on the PR
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

permissions:
  contents: write
  pull-requests: write  

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v5
        with:
          python-version: 3.12
          cache: 'pip' # caching pip dependencies

      - name: Install deepinv and its dependencies
        run: |
          pip install -e .[dataset,denoisers,doc,training]
      - name: Sphinx build
        run: |
          sphinx-build -W docs/source _build
      - name: Run doctests
        env:
          SPHINX_DOCTEST: "1"
        run: |
          # Run doctest with sphinx, to get the extra IGNORE_OUTPUT primitive
          # using plot_gallery=0 to avoid building examples
          sphinx-build -M doctest docs/source docs/build -D plot_gallery=0 -v
      - name: Upload Documentation Artifact
        id: upload-artifact
        uses: actions/upload-artifact@v4
        with:
          name: documentation
          path: _build/
      # Log artifact URL 
      - name: Link to generated docs here
        if: ${{ github.event_name == 'pull_request' && github.event.action != 'closed' }}
        run: |
          echo "Documentation artifact URL: ${{ steps.upload-artifact.outputs.artifact-url }}"
      - name: Deploy to ghpages
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
        with:
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: _build/
          force_orphan: true
          enable_jekyll: false