Control example order via explicit list, not via sorting titles (#1321)

* remove numbers from all example titles * sort examples via JSON file, not title * nest JSON loading so it isn't attempted on import * clearer docstring * use sphinx-gallery master --------- Co-authored-by: Stefan Appelhoff <[email protected]>
mne-tools · Nov 11, 2024 · 81d8afd · 81d8afd
1 parent 2b9b8cc
commit 81d8afd
Show file tree

Hide file tree

Showing 18 changed files with 77 additions and 44 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -185,7 +185,7 @@
     },
     "backreferences_dir": "generated",
     "examples_dirs": "../examples",
-    "within_subsection_order": "ExampleTitleSortKey",
+    "within_subsection_order": "mne_bids.utils._example_sorter",
     "gallery_dirs": "auto_examples",
     "filename_pattern": "^((?!sgskip).)*$",
 }

diff --git a/doc/example_order.json b/doc/example_order.json
@@ -0,0 +1,16 @@
+[
+    "read_bids_datasets.py",
+    "convert_mne_sample.py",
+    "mark_bad_channels.py",
+    "convert_eeg_to_bids.py",
+    "convert_group_studies.py",
+    "rename_brainvision_files.py",
+    "convert_mri_and_trans.py",
+    "convert_ieeg_to_bids.py",
+    "convert_nirs_to_bids.py",
+    "convert_empty_room.py",
+    "bidspath.py",
+    "create_bids_folder.py",
+    "update_bids_datasets.py",
+    "anonymize_dataset.py"
+]
diff --git a/examples/anonymize_dataset.py b/examples/anonymize_dataset.py
@@ -1,7 +1,7 @@
 """
-==============================
-13. Anonymizing a BIDS dataset
-==============================
+==========================
+Anonymizing a BIDS dataset
+==========================
 
 Consider the following scenario:
 

diff --git a/examples/bidspath.py b/examples/bidspath.py
@@ -1,9 +1,9 @@
 """
 .. _bidspath-example:
 
-===============================
-10. An introduction to BIDSPath
-===============================
+===========================
+An introduction to BIDSPath
+===========================
 
 BIDSPath is MNE-BIDS's working horse when it comes to file and folder
 operations. Learn here how to use it.

diff --git a/examples/convert_eeg_to_bids.py b/examples/convert_eeg_to_bids.py
@@ -1,7 +1,7 @@
 """
-===================================
-04. Convert EEG data to BIDS format
-===================================
+===============================
+Convert EEG data to BIDS format
+===============================
 
 In this example, we use MNE-BIDS to create a BIDS-compatible directory of EEG
 data. Specifically, we will follow these steps:

diff --git a/examples/convert_empty_room.py b/examples/convert_empty_room.py
@@ -1,9 +1,9 @@
 """
 .. _ex-convert-empty-room:
 
-====================================
-09. Manually storing empty room data
-====================================
+================================
+Manually storing empty room data
+================================
 
 This example demonstrates how to store empty room data "manually" in the BIDS
 format and how to retrieve them.

diff --git a/examples/convert_group_studies.py b/examples/convert_group_studies.py
@@ -1,7 +1,7 @@
 """
-=====================================
-05. BIDS conversion for group studies
-=====================================
+=================================
+BIDS conversion for group studies
+=================================
 
 Here, we show how to do BIDS conversion for group studies.
 We will use the

diff --git a/examples/convert_ieeg_to_bids.py b/examples/convert_ieeg_to_bids.py
@@ -3,9 +3,9 @@
 
 .. currentmodule:: mne_bids
 
-====================================
-08. Convert iEEG data to BIDS format
-====================================
+================================
+Convert iEEG data to BIDS format
+================================
 
 In this example, we use MNE-BIDS to create a BIDS-compatible directory of iEEG
 data. Specifically, we will follow these steps:

diff --git a/examples/convert_mne_sample.py b/examples/convert_mne_sample.py
@@ -3,9 +3,9 @@
 
 .. _ex-convert-mne-sample:
 
-==========================================
-02. Convert MNE sample data to BIDS format
-==========================================
+======================================
+Convert MNE sample data to BIDS format
+======================================
 
 In this example we will use MNE-BIDS to organize the MNE sample data according
 to the BIDS standard.

diff --git a/examples/convert_mri_and_trans.py b/examples/convert_mri_and_trans.py
@@ -1,7 +1,7 @@
 """
-==============================================================================
-07. Save and load T1-weighted MRI scan along with anatomical landmarks in BIDS
-==============================================================================
+==========================================================================
+Save and load T1-weighted MRI scan along with anatomical landmarks in BIDS
+==========================================================================
 
 When working with MEEG data in the domain of source localization, we usually
 have to deal with aligning several coordinate systems, such as the coordinate

diff --git a/examples/convert_nirs_to_bids.py b/examples/convert_nirs_to_bids.py
@@ -1,7 +1,7 @@
 """
-====================================
-13. Convert NIRS data to BIDS format
-====================================
+================================
+Convert NIRS data to BIDS format
+================================
 
 In this example, we use MNE-BIDS to create a BIDS-compatible directory of NIRS
 data. Specifically, we will follow these steps:

diff --git a/examples/create_bids_folder.py b/examples/create_bids_folder.py
@@ -1,7 +1,7 @@
 """
-=======================================================
-11. Creating BIDS-compatible folder names and filenames
-=======================================================
+===================================================
+Creating BIDS-compatible folder names and filenames
+===================================================
 
 The Brain Imaging Data Structure (BIDS) has standard conventions for file
 names and folder hierarchy. MNE-BIDS comes with convenience functions if you

diff --git a/examples/mark_bad_channels.py b/examples/mark_bad_channels.py
@@ -1,7 +1,7 @@
 """
-=========================================================
-03. Interactive data inspection and bad channel selection
-=========================================================
+=====================================================
+Interactive data inspection and bad channel selection
+=====================================================
 
 You can use MNE-BIDS interactively inspect your  MEG or (i)EEG data.
 Problematic channels can be marked as "bad", for example if the connected

diff --git a/examples/read_bids_datasets.py b/examples/read_bids_datasets.py
@@ -1,9 +1,9 @@
 """
 .. _read_bids_datasets-example:
 
-======================
-01. Read BIDS datasets
-======================
+==================
+Read BIDS datasets
+==================
 
 When working with electrophysiological data in the BIDS format, an important
 resource is the `OpenNeuro <https://openneuro.org/>`_ database. OpenNeuro

diff --git a/examples/rename_brainvision_files.py b/examples/rename_brainvision_files.py
@@ -1,7 +1,7 @@
 """
-=====================================
-06. Rename BrainVision EEG data files
-=====================================
+=================================
+Rename BrainVision EEG data files
+=================================
 
 According to the EEG extension to BIDS [1]_, the `BrainVision data format`_ is
 one of the recommended formats to store EEG data within a BIDS dataset.

diff --git a/examples/update_bids_datasets.py b/examples/update_bids_datasets.py
@@ -1,7 +1,7 @@
 """
-==========================
-12. Updating BIDS datasets
-==========================
+======================
+Updating BIDS datasets
+======================
 
 When working with electrophysiological data in the BIDS format, we usually
 do not have all the metadata stored in the ``Raw`` mne-python object.

diff --git a/mne_bids/utils.py b/mne_bids/utils.py
@@ -8,6 +8,7 @@
 import re
 from datetime import date, datetime, timedelta, timezone
 from os import path as op
+from pathlib import Path
 
 import numpy as np
 from mne import pick_types
@@ -519,6 +520,22 @@ def _import_nibabel(why="work with MRI data"):
         return nibabel
 
 
+# better example sorting, without relying on numbers in example titles
+def _example_sorter(filename):
+    """Sort MNE-BIDS example filenames in a custom order.
+
+    Examples not explicitly listed in `EXAMPLE_ORDER` will be sorted at the end. This
+    function is defined here (instead of in `conf.py`) because it must be *importable*
+    in order for the sphinx gallery config dict in `conf.py` to remain serializable.
+    """
+    with open(Path(__file__).parents[1] / "doc" / "example_order.json") as fid:
+        EXAMPLE_ORDER = json.load(fid)
+
+    if filename not in EXAMPLE_ORDER:
+        EXAMPLE_ORDER.append(filename)
+    return EXAMPLE_ORDER.index(filename)
+
+
 def warn(
     message,
     category=RuntimeWarning,

diff --git a/pyproject.toml b/pyproject.toml
@@ -57,7 +57,7 @@ doc = [
   "seaborn",
   "sphinx-copybutton",
   "sphinx>=7.4.7",
-  "sphinx_gallery",
+  "sphinx_gallery @ https://github.com/sphinx-gallery/sphinx-gallery/archive/refs/heads/master.zip",
 ]
 # Dependencies for using all mne_bids features
 full = [