Modifications to use sphinx gallery for the tutorials.

.github/workflows/deploy-pages.yml

@@ -3,6 +3,7 @@ name: Deploy Sphinx docs to GitHub Pages
 on:
   push:
     branches: [main]
+  pull_request:
   workflow_dispatch:
 
 permissions:
@@ -29,7 +30,7 @@ jobs:
       - name: Install docs dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install -r docs-requirements.txt
 
       - name: Build Sphinx docs
         run: ./build-docs.sh
@@ -44,6 +45,7 @@ jobs:
 
   deploy:
     needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     environment:
       name: github-pages

.gitignore

@@ -70,7 +70,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/source/_static/tutorials.zip
+docs/source/sg_execution_times.rst
+docs/source/tutorials/
 
 # PyBuilder
 .pybuilder/

README.md

@@ -5,7 +5,7 @@ The documentation follows the [Diataxis approach](https://diataxis.fr/).
 ## Building the Docs
 
 1. Create a virtual environment and activate it.
-2. Install the requirements with `pip install -r requirements.txt`.
+2. Install the requirements with `pip install -r docs-requirements.txt`.
 3. Create a new branch. The main branch is protected so you can't push to it directly.
 4. Build the docs locally with `./build-docs.sh`. The new version is available in `docs/build/html/index.html`.
 5. When the local version looks good, push your changes and make a pull request. Pushes to main will build and deploy the new version.

build-docs.sh

@@ -5,18 +5,4 @@ set -euo pipefail
 rm -rf docs/build .jupyter_cache
 mkdir -p docs/source/_static
 
-python - <<'PY'
-from pathlib import Path
-from zipfile import ZipFile, ZIP_DEFLATED
-
-tutorials_dir = Path("docs/source/tutorials")
-archive = Path("docs/source/_static/tutorials.zip")
-
-with ZipFile(archive, "w", compression=ZIP_DEFLATED) as zf:
-    for path in tutorials_dir.rglob("*.ipynb"):
-        zf.write(path, path.relative_to(tutorials_dir.parent))
-PY
-
-sphinx-build -E -a -b html docs/source docs/build/html
-
 sphinx-build -E -a -b html docs/source docs/build/html

docs-requirements.txt

@@ -0,0 +1,7 @@
+sphinx~= 8.1
+pydata-sphinx-theme
+sphinx_copybutton
+myst_nb
+myst-parser
+sphinx_design
+sphinx-gallery

docs/source/_static/custom.css

@@ -1,4 +1,13 @@
 a.gh-link,
 a.gh-link:visited {
   color: black !important;
-}
+}
+
+.sphx-glr-download-link-note,
+.binder-badge,
+.lite-badge,
+.sphx-glr-download-jupyter,
+.sphx-glr-download-python,
+.sphx-glr-download-zip {
+  display: none;
+}

docs/source/conf.py

@@ -18,6 +18,7 @@
     "sphinx_copybutton",
     "myst_nb",
     "sphinx_design",
+    "sphinx_gallery.gen_gallery",
 ]
 
 templates_path = ['_templates']
@@ -29,6 +30,28 @@
     "attrs_inline",
 ]
 
+sphinx_gallery_conf = {
+    "examples_dirs": "tutorials_src",
+    "gallery_dirs": "tutorials",
+
+    # Binder (cloud notebook)
+    "binder": {
+        "org": "python-accelerator-middle-layer",
+        "repo": "documentation",
+        "branch": "main",
+        "binderhub_url": "https://mybinder.org",
+        "dependencies": ["../../requirements.txt"],
+        "use_jupyter_lab": True,
+    },
+}
+
+exclude_patterns += [
+    "tutorials/*.ipynb",
+    "tutorials/*.py",
+    "tutorials/*.zip",
+    "tutorials/*.codeobj.json",
+    "tutorials_src/GALLERY_HEADER.rst"
+]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -42,3 +65,6 @@
 html_sidebars = {
     "reference/index": [],
 }
+html_theme_options = {
+    "secondary_sidebar_items": ["page-toc","sg_download_links", "sg_launcher_links"],
+}

docs/source/index.md

@@ -19,7 +19,7 @@ The features include, among others:
 :hidden:
 :maxdepth: 1
 
-tutorials/index
+Tutorials <tutorials/index>
 how-to/index
 explanation/index
 reference/index

docs/source/tutorials_src/GALLERY_HEADER.rst

@@ -0,0 +1,4 @@
+Tutorials
+=========
+
+Here you can find learning-oriented tutorials that guide you through the functionality of pyAML step by step.

docs/source/tutorials_src/test_page.py

@@ -0,0 +1,56 @@
+"""
+Test page
+=================
+
+This is a minimal Sphinx-Gallery example you can use to verify that:
+
+- the page is picked up by Sphinx-Gallery
+- code cells are executed
+- plots are rendered
+- the Binder button appears on the generated page
+"""
+
+# %%
+# Imports
+# -------
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+# %%
+# Create some data
+# ----------------
+
+x = np.linspace(0, 2 * np.pi, 200)
+y = np.sin(x)
+
+# %%
+# Plot the data
+# -------------
+
+fig, ax = plt.subplots(figsize=(6, 4))
+ax.plot(x, y, label="sin(x)")
+ax.set_xlabel("x")
+ax.set_ylabel("y")
+ax.set_title("Sphinx-Gallery test plot")
+ax.grid(True)
+ax.legend()
+
+plt.show()
+
+# %%
+# A second cell
+# -------------
+
+x2 = np.linspace(0, 2 * np.pi, 30)
+y2 = np.cos(x2)
+
+fig, ax = plt.subplots(figsize=(6, 4))
+ax.scatter(x2, y2, label="cos(x)", marker="o")
+ax.set_xlabel("x")
+ax.set_ylabel("y")
+ax.set_title("Second plot")
+ax.grid(True)
+ax.legend()
+
+plt.show()

requirements.txt

@@ -1,6 +1,3 @@
-sphinx~= 8.1
-pydata-sphinx-theme
-sphinx_copybutton
-myst_nb
-myst-parser
-sphinx_design
+numpy
+matplotlib
+pyaml