Integrate example gallery (#55)

* Created examples gallery * Enabled collapsible subcategories in sidebar * ran nbstripout on example notebooks * added nbstripout to pre-commit --------- Co-authored-by: Josef Cutler <josefcutler@gmail.com>
ibs-lab · Oct 18, 2024 · 8eeec4a · 8eeec4a
1 parent ffaefa6
commit 8eeec4a
Show file tree

Hide file tree

Showing 41 changed files with 3,604 additions and 40,305 deletions.
diff --git a/.gitignore b/.gitignore
@@ -167,6 +167,7 @@ src/cedalion/_version.py
 
 # rendered example notebooks
 docs/examples/*.ipynb
+docs/examples/*/*.ipynb
 
 # API documentation from sphinx-apidoc
 docs/api/*

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -4,11 +4,13 @@ repos:
 # Ruff
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.5.4
+  rev: v0.7.0
   hooks:
-    # Run the linter.
     - id: ruff
       files: ^src/cedalion/
-    # Run the formatter.
-    #- id: ruff-format
-    #  files: ^src/cedalion/
+- repo: https://github.com/kynan/nbstripout
+  rev: 0.7.1
+  hooks:
+    - id: nbstripout
+      files: ^examples/
+
diff --git a/docs/_static/IBS_Logo_sm.png b/docs/_static/IBS_Logo_sm.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -69,3 +69,8 @@
 
 # -- sphinx_autodoc_typehints -------------------------------------------------
 always_use_bars_union = True
+
+# -- Nbsphinx gallery ----------------------------------------------------------------
+nbsphinx_thumbnails = {
+    'examples/*/*': '_static/IBS_Logo_sm.png',
+}
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -0,0 +1,62 @@
+Examples
+========
+
+.. contents::
+   :local:
+
+Getting Started and IO
+----------------------
+
+.. nbgallery::
+   :glob:
+
+   examples/getting_started_io/*
+
+Signal Quality
+-----------------------
+
+.. nbgallery::
+   :glob:
+
+   examples/signal_quality/*
+
+Modeling
+-----------------------
+
+.. nbgallery::
+   :glob:
+
+   examples/modeling/*
+
+Head Models and Image Reconstruction
+-------------------------------------
+
+.. nbgallery::
+   :glob:
+
+   examples/head_models/*
+
+Machine Learning and Data Driven Methods
+----------------------------------------
+
+.. nbgallery::
+   :glob:
+
+   examples/machine_learning/*
+
+Data Augmentation
+-----------------------
+
+.. nbgallery::
+   :caption: Coming soon
+   :glob:
+
+   examples/data_augmentation/*
+
+Plots & Visualization
+-----------------------
+
+.. nbgallery::
+   :glob:
+
+   examples/plots_visualization/*
diff --git a/docs/examples/Makefile b/docs/examples/Makefile
@@ -1,31 +1,25 @@
-EXAMPLE_NOTEBOOKS = 00_test_installation.ipynb \
-					10_xarray_datastructs_fnirs.ipynb \
-					11_recording_container.ipynb \
-					12_plots_example.ipynb \
-					13_data_structures_intro.ipynb \
-					20_scalp_coupling_index.ipynb \
-					21_data_quality_and_pruning.ipynb \
-					22_motion_artefacts_and_correction.ipynb \
-					31_glm_basis_functions.ipynb \
-					32_glm_fingertapping_example.ipynb \
-					33_glm_illustrative_example.ipynb \
-					34_store_hrfs_in_snirf_file.ipynb \
-					40_image_reconstruction.ipynb \
-					41_photogrammetric_optode_coregistration.ipynb \
-					42_1010_system.ipynb \
-					43_crs_and_headmodel.ipynb \
-					50_finger_tapping_lda_classification.ipynb
-
-
-
+EXAMPLE_NOTEBOOKS = getting_started_io/00_test_installation.ipynb \
+                    getting_started_io/10_xarray_datastructs_fnirs.ipynb \
+                    getting_started_io/11_recording_container.ipynb \
+					getting_started_io/13_data_structures_intro.ipynb \
+                    getting_started_io/34_store_hrfs_in_snirf_file.ipynb \
+                    plots_visualization/12_plots_example.ipynb \
+                    machine_learning/50_finger_tapping_lda_classification.ipynb \
+                    modeling/31_glm_basis_functions.ipynb \
+                    modeling/32_glm_fingertapping_example.ipynb \
+                    modeling/33_glm_illustrative_example.ipynb \
+                    signal_quality/20_scalp_coupling_index.ipynb \
+                    signal_quality/21_data_quality_and_pruning.ipynb \
+                    signal_quality/22_motion_artefacts_and_correction.ipynb \
+                    head_models/40_image_reconstruction.ipynb \
+                    head_models/41_photogrammetric_optode_coregistration.ipynb \
+                    head_models/42_1010_system.ipynb \
+                    head_models/43_crs_and_headmodel.ipynb
 
 .PHONY: notebooks
 
 notebooks: $(EXAMPLE_NOTEBOOKS)
 
-$(EXAMPLE_NOTEBOOKS) : %.ipynb : ../../examples/%.ipynb
+$(EXAMPLE_NOTEBOOKS): %.ipynb : ../../examples/%.ipynb
 	jupyter nbconvert --ExecutePreprocessor.store_widget_state=True --to notebook \
-	      --execute --output-dir=. $^
-
-clean:
-	rm -f $(EXAMPLE_NOTEBOOKS)
+	      --execute --output-dir=$(dir $@) $<
diff --git a/docs/examples/index.md b/docs/examples/index.md
diff --git a/docs/index.md b/docs/index.md
@@ -7,12 +7,11 @@ A python-based framework for the data driven analysis of multimodal fNIRS and DO
 ```{toctree}
 :maxdepth: 1
 :caption: Contents
-:titlesonly:
 
 rationale.md
 getting_started/index.md
 data_structures/index.md
-examples/index.md
+examples
 community/index.md
 API <api/modules.rst>
 references.rst

diff --git a/examples/12_plots_example.ipynb b/examples/12_plots_example.ipynb