Add notebooks section in the docs

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",
+    )
+}

doc/source/index.rst

@@ -6,6 +6,7 @@
    :maxdepth: 2
 
    Home <self>
+   notebooks
    api
    changelog
 

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