From e9b4c430757f899936cf1ee3eb03c1b5e262dc0e Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 30 Nov 2023 15:38:18 +0100
Subject: [PATCH 1/3] enh: enable rendering of the jupyter notebooks

---
 docs/conf.py          | 1 +
 docs/examples.rst     | 8 ++++++++
 docs/index.rst        | 1 +
 docs/requirements.txt | 7 ++++++-
 4 files changed, 16 insertions(+), 1 deletion(-)
 create mode 100644 docs/examples.rst

diff --git a/docs/conf.py b/docs/conf.py
index eb4f61580e..09abb8c6db 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -36,6 +36,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinxcontrib.apidoc",
+    "nbsphinx",
     "nipype.sphinxext.apidoc",
     "nipype.sphinxext.plot_workflow",
 ]
diff --git a/docs/examples.rst b/docs/examples.rst
new file mode 100644
index 0000000000..4efb78ab02
--- /dev/null
+++ b/docs/examples.rst
@@ -0,0 +1,8 @@
+Examples
+========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   notebooks/SDC - Theory and physics
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 466e0d4dab..4045ec7d62 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,6 +7,7 @@ Contents
     :maxdepth: 3
 
     installation
+    examples
     methods
     api
     changes
diff --git a/docs/requirements.txt b/docs/requirements.txt
index f6f52b2209..ae30735e4d 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,15 +1,20 @@
 attrs >= 20.1.0
 furo
 importlib_resources
+ipykernel
+ipython
 matplotlib >= 2.2.0
+nbsphinx
 nibabel
 nipype >= 1.5.1
-traits < 6.4
 niworkflows ~= 1.6.3
 numpy
 packaging
+pandoc
 pydot >= 1.2.3
 pydotplus
+scipy
 sphinx >= 7.2.2
 sphinxcontrib-apidoc
 templateflow
+traits < 6.4

From 7f5efb66c505681048b483ff8138e6207bb894d0 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 30 Nov 2023 23:13:46 +0100
Subject: [PATCH 2/3] fix: ensure proper python environment when building docs

---
 .github/workflows/docs-build-pr.yml     | 5 +++++
 .github/workflows/docs-build-update.yml | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/.github/workflows/docs-build-pr.yml b/.github/workflows/docs-build-pr.yml
index 49ce59f696..984b7f8fab 100644
--- a/.github/workflows/docs-build-pr.yml
+++ b/.github/workflows/docs-build-pr.yml
@@ -39,6 +39,11 @@ jobs:
         echo "Building branch/tag ${CURBRANCH:-<unkwown>}, from git ref <$GITHUB_REF>"
         echo "CURBRANCH=${CURBRANCH}" >> ${GITHUB_ENV}
 
+    - name: Set up Python 3
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3
+
     - name: Install GraphViz
       run: |
         sudo apt-get update -y
diff --git a/.github/workflows/docs-build-update.yml b/.github/workflows/docs-build-update.yml
index 0bfa5451f2..e14bcdb10d 100644
--- a/.github/workflows/docs-build-update.yml
+++ b/.github/workflows/docs-build-update.yml
@@ -44,6 +44,11 @@ jobs:
         sudo apt-get update -y
         sudo apt-get install -y --no-install-recommends graphviz
 
+    - name: Set up Python 3
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3
+
     - name: Install dependencies
       run: |
         python -m pip install -U build hatch hatchling pip docutils

From 582a217d993cd3b154414697bd99c4da5e544444 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 30 Nov 2023 23:18:00 +0100
Subject: [PATCH 3/3] fix: pandoc requires install with apt

---
 .github/workflows/docs-build-pr.yml     | 4 ++--
 .github/workflows/docs-build-update.yml | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/docs-build-pr.yml b/.github/workflows/docs-build-pr.yml
index 984b7f8fab..37adf42f99 100644
--- a/.github/workflows/docs-build-pr.yml
+++ b/.github/workflows/docs-build-pr.yml
@@ -44,10 +44,10 @@ jobs:
       with:
         python-version: 3
 
-    - name: Install GraphViz
+    - name: Install GraphViz & pandoc
       run: |
         sudo apt-get update -y
-        sudo apt-get install -y --no-install-recommends graphviz
+        sudo apt-get install -y --no-install-recommends graphviz pandoc
 
     - name: Install dependencies
       run: |
diff --git a/.github/workflows/docs-build-update.yml b/.github/workflows/docs-build-update.yml
index e14bcdb10d..ce349f849c 100644
--- a/.github/workflows/docs-build-update.yml
+++ b/.github/workflows/docs-build-update.yml
@@ -39,10 +39,10 @@ jobs:
         # Pacify git if we were to commit something
         git config user.email "nipreps@gmail.com"
         git config user.name "NiPreps Bot"
-    - name: Install GraphViz
+    - name: Install GraphViz & pandoc
       run: |
         sudo apt-get update -y
-        sudo apt-get install -y --no-install-recommends graphviz
+        sudo apt-get install -y --no-install-recommends graphviz pandoc
 
     - name: Set up Python 3
       uses: actions/setup-python@v4