From e42f6665c63f62a643a5b964b6458dabc7b22507 Mon Sep 17 00:00:00 2001
From: Lunin Leonid <lunin.leonid@gmail.com>
Date: Thu, 14 Nov 2024 12:47:41 +0100
Subject: [PATCH] Switch to myst-nb for.ipynb in docs

Co-authored-by: Felix F Zimmermann <fzimmermann89@gmail.com>
---
 .github/workflows/docs.yml | 40 ++++++--------------------------------
 .gitignore                 |  1 +
 docs/source/conf.py        | 12 ++++++++++++
 docs/source/examples.rst   |  4 ++++
 pyproject.toml             |  7 ++++++-
 5 files changed, 29 insertions(+), 35 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index bb861a8d..cc5ff545 100644
--- a/.github/workflows/docs.yml
+++ b/.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
diff --git a/.gitignore b/.gitignore
index c1694cad..29cb7951 100644
--- a/.gitignore
+++ b/.gitignore
@@ -91,6 +91,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/_notebooks/*
 
 # PyBuilder
 .pybuilder/
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 51102fd0..02f75262 100644
--- a/docs/source/conf.py
+++ b/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')
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index 993517fd..fe24a60a 100644
--- a/docs/source/examples.rst
+++ b/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/*/*
diff --git a/pyproject.toml b/pyproject.toml
index 31798a35..3e1b3a78 100644
--- a/pyproject.toml
+++ b/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",