Repository: mne-tools/mne-bids-pipeline

Issue:
Small things in the docs that are flawed / should be improved
This is mostly a public "note to self" for me, so other devs can ignore this issue.

- Markup is escaped and not rendered:
  <img width="718" alt="Screenshot 2023-01-21 at 11 44 38" src="https://user-images.githubusercontent.com/2046265/213863532-92e608db-cad9-4be6-92ed-e6fa7271bd02.png">

- This parameter should probably appear in a different section / place:
  <img width="246" alt="Screenshot 2023-01-21 at 11 46 29" src="https://user-images.githubusercontent.com/2046265/213863546-20fba5d2-41e5-433d-b647-9e66f974aeac.png">
- Contrasts should not be grouped under statistics, even though stats rely on the values specified there:
  <img width="961" alt="Screenshot 2023-01-21 at 11 46 58" src="https://user-images.githubusercontent.com/2046265/213863554-83aa997f-65eb-4432-af68-76061b3ba515.png">

- `ArbitraryContrast` is not documented:
   <img width="696" alt="Screenshot 2023-01-21 at 11 47 13" src="https://user-images.githubusercontent.com/2046265/213863579-29ba19a2-4b4a-43bd-90f7-a46b50e5afc4.png">



Discussion:

Resolving patch:
diff --git a/mne_bids_pipeline/_config.py b/mne_bids_pipeline/_config.py
--- a/mne_bids_pipeline/_config.py
+++ b/mne_bids_pipeline/_config.py
@@ -45,7 +45,7 @@
 the processing results. If `None`, this will be
 `derivatives/mne-bids-pipeline` inside the BIDS root.
 
-Note: Note
+!!! info
     If specified and you wish to run the source analysis steps, you must
     set [`subjects_dir`][mne_bids_pipeline._config.subjects_dir] as well.
 """
@@ -65,7 +65,7 @@
 If `None`, this will default to
 [`bids_root`][mne_bids_pipeline._config.bids_root]`/derivatives/freesurfer/subjects`.
 
-Note: Note
+!!! info
     This setting is required if you specify
     [`deriv_root`][mne_bids_pipeline._config.deriv_root]
     and want to run the source analysis steps.
@@ -78,7 +78,7 @@
 run `%matplotlib qt` in the command line to open the figures in a separate
 window.
 
-Note: Note
+!!! info
     Enabling interactive mode deactivates parallel processing.
 """
 
@@ -304,7 +304,7 @@
 
 Can also be `None` if you do not want to create bipolar channels.
 
-Note: Note
+!!! info
     The channels used to create the bipolar channels are **not** automatically
     dropped from the data. To drop channels, set `drop_channels`.
 
@@ -540,7 +540,7 @@
 """
 Whether or not to use Maxwell filtering to preprocess the data.
 
-warning:
+!!! warning
     If the data were recorded with internal active compensation (MaxShield),
     they need to be run through Maxwell filter to avoid distortions.
     Bad channels need to be set through BIDS channels.tsv and / or via the
@@ -614,11 +614,11 @@
 
 mf_cal_fname: Optional[str] = None
 """
-warning:
+!!! warning
      This parameter should only be used for BIDS datasets that don't store
      the fine-calibration file
      [according to BIDS](https://bids-specification.readthedocs.io/en/stable/99-appendices/06-meg-file-formats.html#cross-talk-and-fine-calibration-files).
-Path to the Maxwell Filter calibration file. If None the recommended
+Path to the Maxwell Filter calibration file. If `None`, the recommended
 location is used.
 ???+ example "Example"
     ```python
@@ -628,9 +628,10 @@
 
 mf_ctc_fname: Optional[str] = None
 """
-Path to the Maxwell Filter cross-talk file. If None the recommended
+Path to the Maxwell Filter cross-talk file. If `None`, the recommended
 location is used.
-warning:
+
+!!! warning
      This parameter should only be used for BIDS datasets that don't store
      the cross-talk file
      [according to BIDS](https://bids-specification.readthedocs.io/en/stable/99-appendices/06-meg-file-formats.html#cross-talk-and-fine-calibration-files).
@@ -697,7 +698,7 @@
 Notch filter frequency. More than one frequency can be supplied, e.g. to remove
 harmonics. Keep it `None` if no notch filter should be applied.
 
-Note: Note
+!!! info
     The notch filter will be applied before high- and lowpass filtering.
 
 ???+ example "Example"
@@ -811,7 +812,7 @@
 request to create a new type of event by merging repeated events by setting
 this to `'merge'`.
 
-warning:
+!!! warning
     The `'merge'` option is entirely untested in the MNE BIDS Pipeline as of
     April 1st, 2021.
 """
@@ -1016,18 +1017,6 @@
     ```
 """
 
-report_evoked_n_time_points: Optional[int] = None
-"""
-Specifies the number of time points to display for each evoked
-in the report. If None it defaults to the current default in MNE-Python.
-
-???+ example "Example"
-    Only display 5 time points per evoked
-    ```python
-    report_evoked_n_time_points = 5
-    ```
-"""
-
 ###############################################################################
 # ARTIFACT REMOVAL
 # ----------------
@@ -1070,8 +1059,6 @@
 
 # Rejection based on SSP
 # ~~~~~~~~~~~~~~~~~~~~~~
-
-
 n_proj_eog: Dict[str, float] = dict(n_mag=1, n_grad=1, n_eeg=1)
 """
 Number of SSP vectors to create for EOG artifacts for each channel type.
@@ -1141,11 +1128,8 @@
     ```
 """
 
-
 # Rejection based on ICA
 # ~~~~~~~~~~~~~~~~~~~~~~
-
-
 ica_reject: Optional[Dict[str, float]] = None
 """
 Peak-to-peak amplitude limits to exclude epochs from ICA fitting.
@@ -1184,7 +1168,7 @@
 
 Set to `None` to not apply an additional high-pass filter.
 
-Note: Note
+!!! info
       The filter will be applied to raw data which was already filtered
       according to the `l_freq` and `h_freq` settings. After filtering, the
       data will be epoched, and the epochs will be submitted to ICA.
@@ -1254,7 +1238,6 @@
 false-alarm rate increases dramatically.
 """
 
-
 # Rejection based on peak-to-peak amplitude
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1275,7 +1258,7 @@
 `'autoreject_global'`, thresholds for any channel that do not meet this
 requirement will be automatically replaced with those used in `ica_reject`.
 
-Note: Note
+!!! info
       The rejection is performed **after** SSP or ICA, if any of those methods
       is used. To reject epochs **before** fitting ICA, see the
       [`ica_reject`][mne_bids_pipeline._config.ica_reject] setting.
@@ -1287,7 +1270,7 @@
 a dictionary with (hopefully!) optimal thresholds for each channel type. Note
 that using `autoreject` can be a time-consuming process.
 
-Note: Note
+!!! info
       `autoreject` basically offers two modes of operation: "global" and
       "local". In "global" mode, it will try to estimate one rejection
       threshold **per channel type.** In "local" mode, it will generate
@@ -1328,7 +1311,7 @@
 
 decode: bool = True
 """
-Whether to perform decoding (MVPA) on the contrasts specified above as
+Whether to perform decoding (MVPA) on the specified
 [`contrasts`][mne_bids_pipeline._config.contrasts]. Classifiers will be trained
 on entire epochs ("full-epochs decoding"), and separately on each time point
 ("time-by-time decoding"), trying to learn how to distinguish the contrasting
@@ -1338,7 +1321,7 @@
 decoding_epochs_tmin: Optional[float] = 0.0
 """
 The first time sample to use for full epochs decoding. By default it starts
-at 0. If None, it starts at the beginning of the epoch.
+at 0. If `None`,, it starts at the beginning of the epoch.
 """
 
 decoding_epochs_tmax: Optional[float] = None
@@ -1407,7 +1390,7 @@
 determined to correspond to a p-value of 0.05 for the given number of
 participants in a one-tailed test.
 
-Note: Note
+!!! info
     Only points with the same sign will be clustered together.
 """
 
@@ -1423,7 +1406,7 @@
 that the clusters show no significant difference between conditions. This is
 used in the permutation test which takes place after forming the clusters.
 
-Note: Note
+!!! info
     To control how clusters are formed, see
     [`cluster_forming_t_threshold`][mne_bids_pipeline._config.cluster_forming_t_threshold].
 """
@@ -1492,7 +1475,7 @@
 epochs before passing them to time-frequency analysis. Set this to `True` to
 highlight induced activity.
 
-Note: Note
+!!! info
      This also applies to CSP analysis.
 """
 
@@ -1726,7 +1709,7 @@
 This `BIDSPath` can then be modified – or an entirely new `BIDSPath` can be
 generated – and returned by the function, pointing to the T1-weighted image.
 
-Note: Note
+!!! info
     The function accepts and returns a single `BIDSPath`.
 
 ???+ example "Example"
@@ -1915,10 +1898,26 @@ def noise_cov(bids_path):
     ```
 """
 
+###############################################################################
+# Report generation
+# -----------------
+
+report_evoked_n_time_points: Optional[int] = None
+"""
+Specifies the number of time points to display for each evoked
+in the report. If `None`, it defaults to the current default in MNE-Python.
+
+???+ example "Example"
+    Only display 5 time points per evoked
+    ```python
+    report_evoked_n_time_points = 5
+    ```
+"""
+
 report_stc_n_time_points: Optional[int] = None
 """
 Specifies the number of time points to display for each source estimates
-in the report. If None it defaults to the current default in MNE-Python.
+in the report. If `None`, it defaults to the current default in MNE-Python.
 
 ???+ example "Example"
     Only display 5 images per source estimate:
@@ -1999,7 +1998,7 @@ def noise_cov(bids_path):
 processing steps for as long as possible, or drop you into a debugger in case
 of an error.
 
-Note: Note
+!!! info
     Enabling debug mode deactivates parallel processing.
 """
 
diff --git a/mne_bids_pipeline/_run.py b/mne_bids_pipeline/_run.py
--- a/mne_bids_pipeline/_run.py
+++ b/mne_bids_pipeline/_run.py
@@ -321,7 +321,7 @@ def save_logs(*, config: SimpleNamespace, logs) -> None:  # TODO add type
         writer = pd.ExcelWriter(fname, engine="openpyxl")
 
     df.to_excel(writer, sheet_name=sheet_name, index=False)
-    # TODO: "FutureWarning: save is not part of the public API, usage can give
+    # TODO: "Future!!! warning save is not part of the public API, usage can give
     # in unexpected results and will be removed in a future version"
     with warnings.catch_warnings(record=True):
         warnings.simplefilter("ignore")


Test patch: