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

drammock · sappelhoff · web-flow · commit 81d8afd2f727 · 2024-11-11T13:50:53.000-06:00
* 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 &lt;stefan.appelhoff@mailbox.org&gt;
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 = [

Original file line number	Diff line number	Diff line change
`@@ -185,7 +185,7 @@`
`185`	`185`	`},`
`186`	`186`	`"backreferences_dir": "generated",`
`187`	`187`	`"examples_dirs": "../examples",`
`188`		`- "within_subsection_order": "ExampleTitleSortKey",`
	`188`	`+ "within_subsection_order": "mne_bids.utils._example_sorter",`
`189`	`189`	`"gallery_dirs": "auto_examples",`
`190`	`190`	`"filename_pattern": "^((?!sgskip).)*$",`
`191`	`191`	`}`