Restructure configuration options documentation sections (#914)

docs/mkdocs.yml

@@ -103,7 +103,11 @@ nav:
             - Source space & forward solution: settings/source/forward.md
             - Inverse solution: settings/source/inverse.md
         - Report generation: settings/reports/report_generation.md
-        - Execution: settings/execution.md
+        - Caching: settings/caching.md
+        - Parallelization: settings/parallelization.md
+        - Logging: settings/logging.md
+        - Error handling: settings/error_handling.md
+
     - Examples:
         - Examples Gallery: examples/examples.md
         - examples/ds003392.md

docs/source/settings/gen_settings.py

@@ -46,7 +46,13 @@
     "reports": "reports",
     "report generation": "report_generation",
     # root file
-    "execution": "execution",
+    "caching": "caching",
+    # root file
+    "parallelization": "parallelization",
+    # root file
+    "logging": "logging",
+    # root file
+    "error handling": "error_handling",
 }
 # TODO: Make sure these are consistent, autogenerate some based on section names,
 # and/or autogenerate based on inputs/outputs of actual functions.
@@ -76,7 +82,10 @@
     "inverse solution": ("inverse-solution",),
     "reports": (),
     "report generation": ("report",),
-    "execution": (),
+    "caching": ("cache",),
+    "parallelization": ("paralleliation", "dask", "out-of-core"),
+    "logging": ("logging", "error-handling"),
+    "error handling": ("error-handling",),
 }
 
 extra_headers = {

docs/source/v1.9.md.inc

@@ -6,18 +6,22 @@
 - The type annotations in the default configuration file are now easier to read: We
   replaced `Union[X, Y]` with `X | Y` and `Optional[X]` with `X | None`. (#908, #911 by @hoechenberger)
 
-[//]: # (- Whatever (#000 by @whoever))
-
 [//]: # (### :warning: Behavior changes)
 
 [//]: # (- Whatever (#000 by @whoever))
 
 ### :package: Requirements
 
-- We dropped support for Python 3.9. You now need Python 3.10 or newer.
+- We dropped support for Python 3.9. You now need Python 3.10 or newer. (#908 by @hoechenberger)
 
 [//]: # (- Whatever (#000 by @whoever))
 
+### :book: Documentation
+
+- We removed the `Execution` section from configuration options documentation and
+  replaced it with new, more explicit sections (namely, Caching, Parallelization,
+  Logging, and Error handling). (#914 by @hoechenberger)
+
 ### :bug: Bug fixes
 
 - When running the pipeline with [`find_bad_channels_meg`][mne_bids_pipeline._config. find_bad_channels_meg] enabled,

mne_bids_pipeline/_config.py

@@ -2172,10 +2172,44 @@ def noise_cov(bids_path):
 """
 
 # %%
-# # Execution
+# # Caching
 #
-# These options control how the pipeline is executed but should not affect
-# what outputs get produced.
+# These settings control if and how pipeline output is being cached to avoid unnecessary
+# computations on a re-run.
+
+memory_location: PathLike | bool | None = True
+"""
+If not None (or False), caching will be enabled and the cache files will be
+stored in the given directory. The default (True) will use a
+`"_cache"` subdirectory (name configurable via the
+[`memory_subdir`][mne_bids_pipeline._config.memory_subdir]
+variable) in the BIDS derivative root of the dataset.
+"""
+
+memory_subdir: str = "_cache"
+"""
+The caching directory name to use if `memory_location` is `True`.
+"""
+
+memory_file_method: Literal["mtime", "hash"] = "mtime"
+"""
+The method to use for cache invalidation (i.e., detecting changes). Using the
+"modified time" reported by the filesystem (`'mtime'`, default) is very fast
+but requires that the filesystem supports proper mtime reporting. Using file
+hashes (`'hash'`) is slower and requires reading all input files but should
+work on any filesystem.
+"""
+
+memory_verbose: int = 0
+"""
+The verbosity to use when using memory. The default (0) does not print, while
+1 will print the function calls that will be cached. See the documentation for
+the joblib.Memory class for more information."""
+
+# %%
+# # Parallelization
+#
+# These options control parallel processing (e.g., multiple subjects at once),
 
 n_jobs: int = 1
 """
@@ -2215,6 +2249,11 @@ def noise_cov(bids_path):
 The maximum amount of RAM per Dask worker.
 """
 
+# %%
+# # Logging
+#
+# These options control how much logging output is produced.
+
 log_level: Literal["info", "error"] = "info"
 """
 Set the pipeline logging verbosity.
@@ -2225,6 +2264,13 @@ def noise_cov(bids_path):
 Set the MNE-Python logging verbosity.
 """
 
+
+# %%
+# # Error handling
+#
+# These options control how errors while processing the data or the configuration file
+# are handled.
+
 on_error: Literal["continue", "abort", "debug"] = "abort"
 """
 Whether to abort processing as soon as an error occurs, continue with all other
@@ -2235,35 +2281,6 @@ def noise_cov(bids_path):
     Enabling debug mode deactivates parallel processing.
 """
 
-memory_location: PathLike | bool | None = True
-"""
-If not None (or False), caching will be enabled and the cache files will be
-stored in the given directory. The default (True) will use a
-`"_cache"` subdirectory (name configurable via the
-[`memory_subdir`][mne_bids_pipeline._config.memory_subdir]
-variable) in the BIDS derivative root of the dataset.
-"""
-
-memory_subdir: str = "_cache"
-"""
-The caching directory name to use if `memory_location` is `True`.
-"""
-
-memory_file_method: Literal["mtime", "hash"] = "mtime"
-"""
-The method to use for cache invalidation (i.e., detecting changes). Using the
-"modified time" reported by the filesystem (`'mtime'`, default) is very fast
-but requires that the filesystem supports proper mtime reporting. Using file
-hashes (`'hash'`) is slower and requires reading all input files but should
-work on any filesystem.
-"""
-
-memory_verbose: int = 0
-"""
-The verbosity to use when using memory. The default (0) does not print, while
-1 will print the function calls that will be cached. See the documentation for
-the joblib.Memory class for more information."""
-
 config_validation: Literal["raise", "warn", "ignore"] = "raise"
 """
 How strictly to validate the configuration. Errors are always raised for