From bd5c0985e1cf85920bac95c95a7b7e30649d138b Mon Sep 17 00:00:00 2001
From: Joni Herttuainen <joni.herttuainen@epfl.ch>
Date: Mon, 11 Mar 2024 17:22:38 +0100
Subject: [PATCH] Add notebooks section in the docs

---
 doc/source/conf.py       | 12 ++++++++++++
 doc/source/index.rst     |  1 +
 doc/source/notebooks.rst | 31 +++++++++++++++++++++++++++++++
 3 files changed, 44 insertions(+)
 create mode 100644 doc/source/notebooks.rst

diff --git a/doc/source/conf.py b/doc/source/conf.py
index db76920b..0924f54d 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -7,6 +7,7 @@
 # -- Path setup --------------------------------------------------------------
 
 import importlib
+import subprocess
 
 # -- Project information -----------------------------------------------------
 
@@ -25,6 +26,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.autosectionlabel",
+    "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
 ]
@@ -75,3 +77,13 @@
 suppress_warnings = [
     "autosectionlabel.*",
 ]
+
+# generate the link to the notebooks on GitHub
+_base_url = "https://github.com/BlueBrain/snap"
+_git_commit = subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip()
+extlinks = {
+    "notebooks_source": (
+        f"{_base_url}/blob/{_git_commit}/doc/source/notebooks/%s.ipynb",
+        "Notebook: %s",
+    )
+}
diff --git a/doc/source/index.rst b/doc/source/index.rst
index cf2c02a2..b5a214f1 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -6,6 +6,7 @@
    :maxdepth: 2
 
    Home <self>
+   notebooks
    api
    changelog
 
diff --git a/doc/source/notebooks.rst b/doc/source/notebooks.rst
new file mode 100644
index 00000000..86ce6959
--- /dev/null
+++ b/doc/source/notebooks.rst
@@ -0,0 +1,31 @@
+Notebooks
+=========
+
+There is a collection of ``jupyter`` notebooks covering most of the use cases.
+
+Circuit
+-------
+Covers basic circuit usage.
+
+- :notebooks_source:`01_circuits`
+- :notebooks_source:`02_node_populations`
+- :notebooks_source:`03_node_properties`
+- :notebooks_source:`04_edge_properties`
+
+Simulation
+----------
+Covers basic simulation usage.
+
+- :notebooks_source:`05_simulations`
+- :notebooks_source:`06_spike_reports`
+- :notebooks_source:`07_frame_reports`
+
+
+Advanced
+--------
+Covers more advanced use cases.
+
+- :notebooks_source:`08_nodesets`: How to take full advantage of node sets
+- :notebooks_source:`09_node_queries`: Different node queries
+- :notebooks_source:`10_edge_queries`: Different edge queries based on node properties
+- :notebooks_source:`11_iter_connections`: Efficient querying on large edge collections