feat: only publish examples on colab, use action to directly deploy docs

This greatly reduces the size of the repository, as we don't have to
store 100MBs of images on an orphaned branch anymore.

Author: paquiteau

.github/workflows/docs.yml

@@ -74,6 +74,14 @@ jobs:
           export MRINUFFT_BACKEND=cufinufft
           python -m sphinx docs docs_build ${{ contains(github.event.comment.body, 'fast') && '-D plot_gallery=0' || '' }} -j 5
 
+
+      - name: Upload artifact for pages
+        if: ${{ github.event_name == 'workflow_run' }}
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs_build
+          
+          
       - name: Upload artifact
         id: artifact-upload-step
         uses: actions/upload-artifact@v4
@@ -84,6 +92,7 @@ jobs:
           retention-days: 5
 
       - name: Get artifact ID
+        if: contains(github.event.comment.body, '/build-docs') && github.event.issue.pull_request && success()
         id: get-artifact-id
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -120,7 +129,10 @@ jobs:
     runs-on: ubuntu-latest
     needs: build-docs
     if: ${{ github.event_name == 'workflow_run' }}
-
+    permissions:
+      pages: write
+      id-token: write
+      
     steps:
       - name: Get the docs_build artifact
         uses: actions/download-artifact@v4
@@ -133,19 +145,19 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: coverage_badge
-          path: docs_build/_static
+          path: docs_build/examples/_static
           run-id: ${{ github.event.workflow_run.id}}
           github-token: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Display structure of docs
-        run: ls -R docs_build/
-
-      - name: Deploy to GitHub Pages
+      - name: Deploy Examples for Colab import
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs_build
-          destination_dir: .  # Ensure you deploy to the root of the gh-pages branch
-          publish_branch: gh-pages
+          publish_dir: ./docs_build/examples
+          destination_dir: examples
+          publish_branch: colab-examples
           keep_files: false
           force_orphan: true
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

docs/sphinx_add_colab_link.py

@@ -45,7 +45,7 @@ def run(self):
         )
 
         # Generate the Colab URL based on GitHub repo information
-        self.colab_url = f"https://colab.research.google.com/github/mind-inria/mri-nufft/blob/gh-pages/examples/{notebook_repo_relative_path}"
+        self.colab_url = f"https://colab.research.google.com/github/mind-inria/mri-nufft/blob/colab-examples/examples/{notebook_repo_relative_path}"
 
         # Create the HTML button or link
         self.html = f"""<div class="colab-button">