Merge pull request #1 from python-accelerator-middle-layer/notebooks-sphinx-gallery

Modifications to use sphinx gallery for the tutorials.

Author: TeresiaOlsson

.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