Repository: nilearn/nilearn

Issue:
[DOC] Error in docstring for `nilearn.glm.first_level.first_level_from_bids`
### Is there an existing issue for this?

- [X] I have searched the existing issues

### Describe your proposed suggestion in detail.

The autodocs for [`nilearn.glm.first_level.first_level_from_bids`](https://nilearn.github.io/dev/modules/generated/nilearn.glm.first_level.first_level_from_bids.html) say to use kwargs prefixed with `confound_`, which will be passed to [`nilearn.interfaces.fmriprep.load_confounds`](https://nilearn.github.io/dev/modules/generated/nilearn.interfaces.fmriprep.load_confounds.html), but that is incorrect as it should be `confounds_` (plural). Also:
1. No error is raised if the wrong prefix is used (and it is unclear what happens to kwargs not starting with `confounds`)
2. The rendering of some parts of the docstring does not look good (see screenshot below)

<img width="517" alt="Screenshot 2024-03-26 at 2 48 36 PM" src="https://github.com/nilearn/nilearn/assets/29051929/2f037e3a-e6ba-474b-bcc7-2e6b69c59423">

### List any pages that would be impacted.

https://nilearn.github.io/dev/modules/generated/nilearn.interfaces.fmriprep.load_confounds.html


Discussion:
Thx for opening. I'm pretty sure you can fix it ;-)

Resolving patch:
diff --git a/nilearn/glm/first_level/first_level.py b/nilearn/glm/first_level/first_level.py
--- a/nilearn/glm/first_level/first_level.py
+++ b/nilearn/glm/first_level/first_level.py
@@ -1098,12 +1098,19 @@ def first_level_from_bids(
     """Create FirstLevelModel objects and fit arguments \
        from a :term:`BIDS` dataset.
 
-    If ``t_r`` is ``None`` this function will attempt
-    to load it from a bold.json.
-    If ``slice_time_ref`` is  `None` this function will attempt
-    to infer it from a bold.json.
-    Otherwise ``t_r`` and ``slice_time_ref`` are taken as given,
-    but a warning may be raised if they are not consistent with the bold.json.
+    If ``t_r`` is ``None``, this function will attempt
+    to load it from a ``bold.json``.
+    If ``slice_time_ref`` is  ``None``, this function will attempt
+    to infer it from a ``bold.json``.
+    Otherwise, ``t_r`` and ``slice_time_ref`` are taken as given,
+    but a warning may be raised if they are not consistent with the
+    ``bold.json``.
+
+    All parameters not described here are passed to
+    :class:`~nilearn.glm.first_level.FirstLevelModel`.
+
+    The subject label of the model will be determined directly
+    from the :term:`BIDS` dataset.
 
     Parameters
     ----------
@@ -1112,60 +1119,57 @@ def first_level_from_bids(
         Should contain subject folders and a derivatives folder.
 
     task_label : :obj:`str`
-        Task_label as specified in the file names like _task-<task_label>_.
+        Task_label as specified in the file names like ``_task-<task_label>_``.
 
     space_label : :obj:`str`, optional
         Specifies the space label of the preprocessed bold.nii images.
-        As they are specified in the file names like _space-<space_label>_.
+        As they are specified in the file names like ``_space-<space_label>_``.
 
     sub_labels : :obj:`list` of :obj:`str`, optional
         Specifies the subset of subject labels to model.
-        If 'None', will model all subjects in the dataset.
+        If ``None``, will model all subjects in the dataset.
 
         .. versionadded:: 0.10.1
 
-    img_filters : :obj:`list` of :obj:`tuple` (str, str), optional
-        Filters are of the form (field, label). Only one filter per field
+    img_filters : :obj:`list` of :obj:`tuple` (:obj:`str`, :obj:`str`), \
+        optional
+        Filters are of the form ``(field, label)``. Only one filter per field
         allowed.
         A file that does not match a filter will be discarded.
-        Possible filters are 'acq', 'ce', 'dir', 'rec', 'run', 'echo', 'res',
-        'den', and 'desc'.
-        Filter examples would be ('desc', 'preproc'), ('dir', 'pa')
-        and ('run', '10').
+        Possible filters are ``'acq'``, ``'ce'``, ``'dir'``, ``'rec'``,
+        ``'run'``, ``'echo'``, ``'res'``, ``'den'``, and ``'desc'``.
+        Filter examples would be ``('desc', 'preproc')``, ``('dir', 'pa')``
+        and ``('run', '10')``.
 
-    slice_time_ref : :obj:`float` between 0.0 and 1.0, default=0.0
+    slice_time_ref : :obj:`float` between ``0.0`` and ``1.0``, default= ``0.0``
         This parameter indicates the time of the reference slice used in the
         slice timing preprocessing step of the experimental runs. It is
-        expressed as a fraction of the t_r (time repetition), so it can have
-        values between 0. and 1.
+        expressed as a fraction of the ``t_r`` (time repetition), so it can
+        have values between ``0.`` and ``1.``
 
         .. deprecated:: 0.10.1
 
-            The default=0 for ``slice_time_ref`` will be deprecated.
-            The default value will change to 'None' in 0.12.
+            The default= ``0`` for ``slice_time_ref`` will be deprecated.
+            The default value will change to ``None`` in 0.12.
 
-    derivatives_folder : :obj:`str`, default="derivatives".
+    derivatives_folder : :obj:`str`, default= ``"derivatives"``.
         derivatives and app folder path containing preprocessed files.
-        Like "derivatives/FMRIPREP".
-
-    All other parameters correspond to a `FirstLevelModel` object, which
-    contains their documentation.
-    The subject label of the model will be determined directly
-    from the :term:`BIDS` dataset.
+        Like ``"derivatives/FMRIPREP"``.
 
-    kwargs: :obj:`dict`
+    kwargs : :obj:`dict`
 
-        .. versionadded:: 0.10.3
+        Keyword arguments to be passed to functions called within this
+        function.
 
-    Keyword arguments to be passed to functions called within this function.
+        Kwargs prefixed with ``confounds_``
+        will be passed to :func:`~nilearn.interfaces.fmriprep.load_confounds`.
+        This allows ``first_level_from_bids`` to return
+        a specific set of confounds by relying on confound loading strategies
+        defined in :func:`~nilearn.interfaces.fmriprep.load_confounds`.
+        If no kwargs are passed, ``first_level_from_bids`` will return
+        all the confounds available in the confounds TSV files.
 
-    Kwargs prefixed with ``confound_``
-    will be passed to :func:`~nilearn.interfaces.fmriprep.load_confounds`.
-    This allows ``first_level_from_bids`` to return
-    a specific set of confounds by relying on confound loading strategies
-    defined in :func:`~nilearn.interfaces.fmriprep.load_confounds`.
-    If no kwargs are passed, ``first_level_from_bids`` will return
-    all the confounds available in the confounds TSV files.
+        .. versionadded:: 0.10.3
 
     Examples
     --------
@@ -1235,19 +1239,23 @@ def first_level_from_bids(
 
     Returns
     -------
-    models : list of `FirstLevelModel` objects
-        Each FirstLevelModel object corresponds to a subject.
+    models : list of :class:`~nilearn.glm.first_level.FirstLevelModel` objects
+        Each :class:`~nilearn.glm.first_level.FirstLevelModel` object
+        corresponds to a subject.
         All runs from different sessions are considered together
         for the same subject to run a fixed effects analysis on them.
 
     models_run_imgs : list of list of Niimg-like objects,
-        Items for the FirstLevelModel fit function of their respective model.
+        Items for the :class:`~nilearn.glm.first_level.FirstLevelModel`
+        fit function of their respective model.
 
     models_events : list of list of pandas DataFrames,
-        Items for the FirstLevelModel fit function of their respective model.
+        Items for the :class:`~nilearn.glm.first_level.FirstLevelModel`
+        fit function of their respective model.
 
-    models_confounds : list of list of pandas DataFrames or None,
-        Items for the FirstLevelModel fit function of their respective model.
+    models_confounds : list of list of pandas DataFrames or ``None``,
+        Items for the :class:`~nilearn.glm.first_level.FirstLevelModel`
+        fit function of their respective model.
 
     """
     if slice_time_ref == 0:


Test patch: