Fix binder integration

.github/workflows/binder.yml

@@ -0,0 +1,50 @@
+name: Publish Binder environment
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  publish-binder:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt -r binder/requirements.txt
+
+      - name: Build Sphinx documentation
+        run: ./build-docs.sh
+
+      - name: Prepare Binder branch
+        run: |
+          mkdir -p binder-publish/binder
+          mkdir -p binder-publish/notebooks/tutorials
+
+          # Keep the Binder configuration inside binder/
+          cp -a binder/. binder-publish/binder/
+
+          # Copy notebooks generated by Sphinx-Gallery
+          cp -a docs/build/html/tutorials/. \
+            binder-publish/notebooks/tutorials/
+
+      - name: Publish binder branch
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: binder-publish
+          publish_branch: binder
+          force_orphan: true

.github/workflows/deploy-pages.yml

@@ -30,22 +30,11 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt -r docs/requirements.txt
+          pip install -r requirements.txt -r binder/requirements.txt
 
       - name: Build Sphinx docs
         run: ./build-docs.sh
 
-      - name: Add Binder environment configuration
-        run: cp environment.yml docs/build/html/environment.yml
-
-      - name: Publish built docs for Binder
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/build/html
-          publish_branch: gh-pages
-
       - name: Configure GitHub Pages
         uses: actions/configure-pages@v6
 

README.md

@@ -6,13 +6,13 @@ The documentation follows the [Diataxis approach](https://diataxis.fr/).
 
 1. Clone the repository
 2. Create a virtual environment and activate it.
-3. Install the requirements with `pip install -r requirements.txt -r docs/requirements.txt`.
+3. Install the requirements with `pip install -r requirements.txt -r binder/requirements.txt`.
 4. Create a new branch. The main branch is protected so you can't push to it directly.
 5. Build the docs locally with `./build-docs.sh`. The new version is available in `docs/build/html/index.html`.
 6. When the local version looks good, push your changes and make a pull request. Pushes to main will build and deploy the new version.
 
 For the notebooks it is necessary to have the required pyAML packages installed in the environment.
-If you add a new dependency remember to also add it in the `docs/requirements.txt` or it will not be built correctly.
+If you add a new dependency remember to also add it in the `binder/requirements.txt` or it will not be built correctly.
 
 ## Developing Content
 

environment.yml → binder/environment.yml

@@ -5,4 +5,4 @@ dependencies:
   - python=3.11.0
   - pip
   - pip:
-      - -r binder/requirements.txt
+      - -r requirements.txt

binder/requirements.txt

@@ -0,0 +1,4 @@
+pyaml
+pyaml-cs-oa[tango,epics]
+tango-pyaml
+pyaml-test-lattice

docs/source/conf.py

@@ -49,7 +49,7 @@
         # the generated documentation and notebooks here.
         "branch": "gh-pages",
         "binderhub_url": "https://mybinder.org",
-        "dependencies": ["../requirements.txt"],
+        "dependencies": ["../../binder/requirements.txt"],
         "notebooks_dir": "notebooks",
         "use_jupyter_lab": True,
     },