sort examples via JSON file, not title

Author: drammock

doc/conf.py

@@ -182,7 +182,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).)*$",
 }

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"
+]

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
@@ -518,6 +519,24 @@ def _import_nibabel(why="work with MRI data"):
         return nibabel
 
 
+# better example sorting, without relying on numbers in example titles
+with open(Path(__file__).parents[1] / "doc" / "example_order.json") as fid:
+    EXAMPLE_ORDER = json.load(fid)
+
+
+def _example_sorter(filename):
+    """Sort for MNE-BIDS example filenames in a custom order.
+
+    Examples not explicitly listed in `EXAMPLE_ORDER` above will be sorted at the end.
+    This is here (instead of in `conf.py`) because it needs to be *importable* for it
+    to work correctly in Sphinx Gallery / maintain serializability of the sphinx gallery
+    config dict in `conf.py`.
+    """
+    if filename not in EXAMPLE_ORDER:
+        EXAMPLE_ORDER.append(filename)
+    return EXAMPLE_ORDER.index(filename)
+
+
 def warn(
     message,
     category=RuntimeWarning,