Switch to myst-nb for.ipynb in docs

Co-authored-by: Felix F Zimmermann <[email protected]>

.github/workflows/docs.yml

@@ -120,14 +120,14 @@ jobs:
         run: |
           notebook=${{ matrix.notebook }}
           echo "ARTIFACT_NAME=${notebook/.ipynb/}" >> $GITHUB_OUTPUT
-          echo "HTML_RESULT=${notebook/.ipynb/.html}" >> $GITHUB_OUTPUT
+          echo "IPYNB_EXECUTED=${notebook}" >> $GITHUB_OUTPUT
 
       - name: Upload notebook
         uses: actions/upload-artifact@v4
         if: always()
         with:
           name: ${{ steps.artifact_names.outputs.ARTIFACT_NAME }}
-          path: ${{ github.workspace }}/nb-runner.out/${{ steps.artifact_names.outputs.HTML_RESULT }}
+          path: ${{ github.workspace }}/nb-runner.out/${{ steps.artifact_names.outputs.IPYNB_EXECUTED }}
         env:
           RUNNER: ${{ toJson(runner) }}
 
@@ -150,39 +150,11 @@ jobs:
       - name: Install mrpro and dependencies
         run: pip install --upgrade --upgrade-strategy "eager" .[docs]
 
-      - name: Download notebook html files
+      - name: Download executed notebook ipynb files
         id: download
         uses: actions/download-artifact@v4
         with:
-          path: ./docs/source/notebook_artifact/
-
-      - name: Copy notebook html files
-        run: |
-          mkdir ./docs/source/_notebooks
-          cd ./docs/source/notebook_artifact/
-          notebooks=$(grep -rl --include='*' './')
-          for nb in $notebooks
-          do
-            echo "current jupyter-notebook: $nb"
-            cp ./$nb ../_notebooks/
-          done
-
-      - name: List of notebooks
-        run: |
-          cd ./docs/source/_notebooks/
-          notebooks=$(grep -rl --include='*.html' './')
-          cd ../
-          echo "" >> examples.rst
-          for nb in $notebooks
-          do
-            echo "   notebook_${nb/.html/.rst}" >> examples.rst
-            notebook_description=$(grep '<h1 id=' ./_notebooks/$nb | sed 's/.*">\(.*\)<a class=.*/\1/')
-            echo $notebook_description
-            echo $notebook_description > "notebook_${nb/.html/.rst}"
-            echo "========" >> "notebook_${nb/.html/.rst}"
-            echo ".. raw:: html" >> "notebook_${nb/.html/.rst}"
-            echo "   :file: ./_notebooks/$nb" >> "notebook_${nb/.html/.rst}"
-          done
+          path: ./docs/source/_notebooks/
 
       - name: Build docs
         run: |
@@ -195,7 +167,7 @@ jobs:
         with:
           name: Documentation
           path: docs/build/html/
-      
+
       - run: echo 'Artifact url ${{ steps.save_docu.outputs.artifact-url }}'
 
       - run: echo 'Event number ${{ github.event.number }}'
@@ -225,7 +197,7 @@ jobs:
   deploy:
     if: github.ref == 'refs/heads/main'
     permissions:
-        pages: write   
+        pages: write
         id-token: write
     environment:
       name: github-pages

.gitignore

@@ -91,6 +91,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/_notebooks/*
 
 # PyBuilder
 .pybuilder/

docs/source/conf.py

@@ -34,6 +34,9 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
+    'myst_nb',
+    'sphinx.ext.mathjax',
+    'sphinx-mathjax-offline'
 ]
 autosummary_generate = True
 autosummary_imported_members = False
@@ -43,6 +46,11 @@
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 source_suffix = {'.rst': 'restructuredtext', '.txt': 'restructuredtext', '.md': 'markdown'}
 
+myst_enable_extensions = [
+    "amsmath",
+    "dollarmath",
+]
+nb_execution_mode = "off"
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -69,3 +77,7 @@
         },
     ],
 }
+
+def setup(app):
+    # forces mathjax on all pages
+    app.set_html_assets_policy('always')

docs/source/examples.rst

@@ -6,3 +6,7 @@ All of the notebooks can directly be run via binder or colab from the repo.
 
 .. toctree::
    :maxdepth: 1
+   :caption: Contents:
+   :glob:
+
+   _notebooks/*/*

pyproject.toml

@@ -65,7 +65,12 @@ test = [
     "pytest-cov",
     "pytest-xdist",
 ]
-docs = ["sphinx", "sphinx_rtd_theme", "sphinx-pyproject"]
+docs = ["sphinx",
+    "sphinx_rtd_theme",
+    "sphinx-pyproject",
+    "myst-nb",
+    "sphinx-mathjax-offline",
+    ]
 notebook = [
     "zenodo_get",
     "ipykernel",