Repository: nilearn/nilearn

Issue:
sort entries in docs.py in alphabetical order
              If there is no objection I would like in another PR to sort the entries in this file alphabetically: this may help navigate it.

_Originally posted by @Remi-Gau in https://github.com/nilearn/nilearn/pull/3621#discussion_r1147498458_
            


Discussion:

Resolving patch:
diff --git a/nilearn/_utils/docs.py b/nilearn/_utils/docs.py
--- a/nilearn/_utils/docs.py
+++ b/nilearn/_utils/docs.py
@@ -3,6 +3,8 @@
 docdict contains the standard documentation entries
 used across Nilearn.
 
+Entries are listed in alphabetical order.
+
 source: Eric Larson and MNE-python team.
 https://github.com/mne-tools/mne-python/blob/main/mne/utils/docs.py
 """
@@ -10,192 +12,93 @@
 import sys
 
 
-###################################
+
+
+##############################################################################
 # Standard documentation entries
 #
+# Entries are listed in alphabetical order.
+#
 docdict = dict()
 
-# Verbose
-verbose = """
-verbose : :obj:`int`, optional
-    Verbosity level (0 means no message).
-    Default={}."""
-docdict['verbose'] = verbose.format(1)
-docdict['verbose0'] = verbose.format(0)
-
-# ax
-docdict['ax'] = """
-ax : :class:`~matplotlib.axes.Axes`
-    The matplotlib axes in which the plots will be drawn."""
-
-# Legacy_format
-docdict['legacy_format'] = """
-legacy_format : :obj:`bool`, optional
-    If set to ``True``, the fetcher will return recarrays. Otherwise,
-    it will return pandas dataframes.
-    Default=True."""
-
-# Resume
-docdict['resume'] = """
-resume : :obj:`bool`, optional
-    Whether to resume download of a partly-downloaded file.
-    Default=True."""
-
-# Data_dir
-docdict['data_dir'] = """
-data_dir : :obj:`pathlib.Path` or :obj:`str`, optional
-    Path where data should be downloaded. By default,
-    files are downloaded in home directory."""
+# annotate
+docdict['annotate'] = """
+annotate : :obj:`bool`, optional
+    If ``annotate`` is ``True``, positions and left/right annotation
+    are added to the plot. Default=True."""
 
-# URL
-docdict['url'] = """
-url : :obj:`str`, optional
-    URL of file to download.
-    Override download URL. Used for test only (or if you
-    setup a mirror of the data).
-    Default=None."""
+# avg_method
+docdict['avg_method'] = """
+avg_method : {'mean', 'median', 'min', 'max', custom function}, optional
+    How to average vertex values to derive the face value:
 
-# Smoothing_fwhm
-docdict['smoothing_fwhm'] = """
-smoothing_fwhm : :obj:`float`, optional.
-    If ``smoothing_fwhm`` is not ``None``, it gives
-    the :term:`full-width at half maximum<FWHM>` in millimeters
-    of the spatial smoothing to apply to the signal."""
+        - ``mean``: results in smooth boundaries
+        - ``median``: results in sharp boundaries
+        - ``min`` or ``max``: for sparse matrices
+        - ``custom function``: You can also pass a custom function
+          which will be executed though :func:`numpy.apply_along_axis`.
+          Here is an example of a custom function:
 
-# Second_level_input
-docdict['second_level_input'] = """
-second_level_input : :obj:`list` of \
-:class:`~nilearn.glm.first_level.FirstLevelModel` objects \
-or :class:`pandas.DataFrame` or :obj:`list` of Niimg-like objects.
+            .. code-block:: python
 
-    - Giving :class:`~nilearn.glm.first_level.FirstLevelModel` objects
-      will allow to easily compute the second level contrast of arbitrary first
-      level contrasts thanks to the ``first_level_contrast`` argument of
-      :meth:`~nilearn.glm.first_level.FirstLevelModel.compute_contrast`.
-      Effect size images will be computed for each model to contrast at
-      the second level.
-    - If a :class:`~pandas.DataFrame`, then it has to contain
-      ``subject_label``, ``map_name`` and ``effects_map_path``. It can
-      contain multiple maps that would be selected during contrast estimation
-      with the argument ``first_level_contrast`` of
-      :meth:`~nilearn.glm.first_level.FirstLevelModel.compute_contrast`.
-      The :class:`~pandas.DataFrame` will be sorted based on
-      the ``subject_label`` column to avoid order inconsistencies when
-      extracting the maps. So the rows of the automatically computed
-      design matrix, if not provided, will correspond to the sorted
-      ``subject_label`` column.
-    - If a :obj:`list` of Niimg-like objects then this is taken
-      literally as Y for the model fit and ``design_matrix`` must be
-      provided.
+                def custom_function(vertices):
+                    return vertices[0] * vertices[1] * vertices[2]
 
 """
 
-# Second_level_contrast
-docdict['second_level_contrast'] = """
-second_level_contrast : :obj:`str` or :class:`numpy.ndarray` of shape\
-(n_col), optional
-    Where ``n_col`` is the number of columns of the design matrix.
-    The string can be a formula compatible with :meth:`pandas.DataFrame.eval`.
-    Basically one can use the name of the conditions as they appear in the
-    design matrix of the fitted model combined with operators +- and combined
-    with numbers with operators +-`*`/. The default (None) is accepted if the
-    design matrix has a single column, in which case the only possible
-    contrast array((1)) is applied; when the design matrix has multiple
-    columns, an error is raised."""
-
-# fwhm
-docdict['fwhm'] = """
-fwhm : scalar, :class:`numpy.ndarray`, or :obj:`tuple`, or :obj:`list`,\
-or 'fast' or None, optional
-    Smoothing strength, as a :term:`full-width at half maximum<FWHM>`,
-    in millimeters:
-
-        - If a nonzero scalar is given, width is identical in all 3 directions.
-        - If a :class:`numpy.ndarray`, :obj:`tuple`, or :obj:`list` is given,
-          it must have 3 elements, giving the :term:`FWHM` along each axis.
-          If any of the elements is zero or None, smoothing is not performed
-          along that axis.
-        - If `fwhm='fast'`, a fast smoothing will be performed with a filter
-          [0.2, 1, 0.2] in each direction and a normalisation to preserve the
-          local average value.
-        - If ``fwhm`` is None, no filtering is performed (useful when just
-          removal of non-finite values is needed).
-
-    .. note::
+# ax
+docdict['ax'] = """
+ax : :class:`~matplotlib.axes.Axes`
+    The matplotlib axes in which the plots will be drawn."""
 
-        In corner case situations, `fwhm` is simply kept to None when `fwhm`
-        is specified as `fwhm=0`.
+# axes
+docdict['axes'] = """
+axes : :class:`matplotlib.axes.Axes`, or 4 tuple\
+of :obj:`float`: (xmin, ymin, width, height), optional
+    The axes, or the coordinates, in matplotlib figure
+    space, of the axes used to display the plot.
+    If ``None``, the complete figure is used."""
 
+# bg_img
+docdict['bg_img'] = """
+bg_img : Niimg-like object, optional
+    See :ref:`extracting_data`.
+    The background image to plot on top of.
 """
 
-# Standardize
-standardize = """
-standardize : :obj:`bool`, optional.
-    If ``standardize`` is True, the data are centered and normed:
-    their mean is put to 0 and their variance is put to 1 in the
-    time dimension.
-    Default={}."""
-docdict['standardize'] = standardize.format('True')
-docdict['standardize_false'] = standardize.format('False')
-
-# standardize_confounds
-docdict['standardize_confounds'] = """
-standardize_confounds : :obj:`bool`, optional
-    If set to True, the confounds are z-scored: their mean is put
-    to 0 and their variance to 1 in the time dimension.
-    Default=True."""
-
-# ensure_finite
-docdict['ensure_finite'] = """
-ensure_finite : :obj:`bool`, optional
-    If True, the non-finite values (NANs and infs) found in the data
-    will be replaced by zeros."""
-
-# detrend
-docdict['detrend'] = """
-detrend : :obj:`bool`, optional
-    Whether to detrend signals or not."""
-
-# Target_affine
-docdict['target_affine'] = """
-target_affine : :class:`numpy.ndarray`, optional.
-    If specified, the image is resampled corresponding to this new affine.
-    ``target_affine`` can be a 3x3 or a 4x4 matrix.
-    Default=None."""
-
-# Target_shape
-docdict['target_shape'] = """
-target_shape : :obj:`tuple` or :obj:`list`, optional.
-    If specified, the image will be resized to match this new shape.
-    ``len(target_shape)`` must be equal to 3.
-
-    .. note::
-        If ``target_shape`` is specified, a ``target_affine`` of shape
-        ``(4, 4)`` must also be given.
+# bg_on_data
+docdict['bg_on_data'] = r"""
+bg_on_data : :obj:`bool`, optional
+    If ``True`` and a ``bg_map`` is specified,
+    the ``surf_data`` data is multiplied by the background
+    image, so that e.g. sulcal depth is jointly visible with ``surf_data``.
+    Otherwise, the background image will only be visible where there
+    is no surface data (either because ``surf_data`` contains ``nan``\s
+    or because is was thresholded).
 
-    Default=None."""
+        .. note::
+            This non-uniformly changes the surf_data values according
+            to e.g the sulcal depth.
 
-# Low_pass
-docdict['low_pass'] = """
-low_pass : :obj:`float` or None, optional
-    Low cutoff frequency in Hertz. If specified, signals above this
-    frequency will be filtered out. If None, no low-pass filtering
-    will be performed. Default=None."""
+"""
 
-# lower_cutoff
-docdict['lower_cutoff'] = """
-lower_cutoff : :obj:`float`, optional
-    Lower fraction of the histogram to be discarded."""
+# bg_vmax
+docdict['bg_vmax'] = """
+bg_vmin : :obj:`float`, optional
+    vmax for ``bg_img``."""
 
-# upper_cutoff
-docdict['upper_cutoff'] = """
-upper_cutoff : :obj:`float`, optional
-    Upper fraction of the histogram to be discarded."""
+# bg_vmin
+docdict['bg_vmin'] = """
+bg_vmin : :obj:`float`, optional
+    vmin for ``bg_img``."""
 
-# connected
-docdict['connected'] = """
-connected : :obj:`bool`, optional
-    If connected is True, only the largest connect component is kept."""
+# black_bg
+docdict['black_bg'] = """
+black_bg : :obj:`bool`, or 'auto', optional
+    If ``True``, the background of the image is set to be black.
+    If you wish to save figures with a black background, you
+    will need to pass facecolor='k', edgecolor='k'
+    to :func:`matplotlib.pyplot.savefig`."""
 
 # border_size
 docdict['border_size'] = """
@@ -203,110 +106,89 @@
     The size, in :term:`voxel` of the border used on the side of
     the image to determine the value of the background."""
 
-# opening
-docdict['opening'] = """
-opening : :obj:`bool` or :obj:`int`, optional
-    This parameter determines whether a morphological
-    :term:`opening<Opening>` is performed, to keep only large structures.
-    This step is useful to remove parts of the skull that might have been
-    included. ``opening`` can be:
+# cbar_tick_format
+docdict['cbar_tick_format'] = """
+cbar_tick_format : :obj:`str`, optional
+    Controls how to format the tick labels of the colorbar.
+    Ex: use "%%.2g" to display using scientific notation."""
 
-        - A boolean : If False, no :term:`opening<Opening>` is performed.
-          If True, it is equivalent to ``opening=1``.
-        - An integer `n`: The :term:`opening<Opening>` is performed via `n`
-          :term:`erosions<Erosion>` (see :func:`scipy.ndimage.binary_erosion`).
-          The largest connected component is then estimated if ``connected`` is
-          set to True, and 2`n` :term:`dilation<Dilation>` operations are
-          performed (see :func:`scipy.ndimage.binary_dilation`) followed by
-          `n` :term:`erosions<Erosion>`. This corresponds to 1
-          :term:`opening<Opening>` operation of order `n` followed by a
-          :term:`closing<Closing>` operator of order `n`.
+# classifier_options
+svc = "Linear support vector classifier"
+logistic = "Logistic regression"
+rc = "Ridge classifier"
+dc = "Dummy classifier with stratified strategy"
 
-    .. note::
+docdict['classifier_options'] = f"""
 
-        Turning off :term:`opening<Opening>` (``opening=False``) will also
-        prevent any smoothing applied to the image during the mask computation.
+        - `svc`: :class:`{svc} <sklearn.svm.SVC>` with L2 penalty.
+            .. code-block:: python
 
-"""
+                svc = LinearSVC(penalty='l2',
+                                max_iter=1e4)
 
-# mask_type
-docdict['mask_type'] = """
-mask_type : {'whole-brain', 'gm', 'wm'}, optional
-    Type of mask to be computed:
+        - `svc_l2`: :class:`{svc} <sklearn.svm.SVC>` with L2 penalty.
+            .. note::
+                Same as option `svc`.
 
-        - 'whole-brain': Computes the whole-brain mask.
-        - 'gm': Computes the grey-matter mask.
-        - 'wm': Computes the white-matter mask.
+        - `svc_l1`: :class:`{svc} <sklearn.svm.SVC>` with L1 penalty.
+            .. code-block:: python
 
-    Default = 'whole-brain'.
+                svc_l1 = LinearSVC(penalty='l1',
+                                   dual=False,
+                                   max_iter=1e4)
+
+        - `logistic`: \
+            :class:`{logistic} <sklearn.linear_model.LogisticRegression>` \
+            with L2 penalty.
+            .. code-block:: python
+
+                logistic = LogisticRegression(penalty='l2',
+                                              solver='liblinear')
+
+        - `logistic_l1`: \
+            :class:`{logistic} <sklearn.linear_model.LogisticRegression>` \
+            with L1 penalty.
+            .. code-block:: python
 
-"""
+                logistic_l1 = LogisticRegression(penalty='l1',
+                                                 solver='liblinear')
 
-# High pass
-docdict['high_pass'] = """
-high_pass : :obj:`float`, optional
-    High cutoff frequency in Hertz. If specified, signals below this
-    frequency will be filtered out. Default=None."""
+        - `logistic_l2`: \
+            :class:`{logistic} <sklearn.linear_model.LogisticRegression>` \
+            with L2 penalty
+            .. note::
+                Same as option `logistic`.
 
-# t_r
-docdict['t_r'] = """
-t_r : :obj:`float` or None, optional
-    Repetition time, in seconds (sampling period).
-    Set to ``None`` if not provided.
-    Default=None."""
+        - `ridge_classifier`: \
+            :class:`{rc} <sklearn.linear_model.RidgeClassifierCV>`.
+            .. code-block:: python
 
-# mask_img
-docdict['mask_img'] = """
-mask_img : Niimg-like object
-    Object used for masking the data."""
+                ridge_classifier = RidgeClassifierCV()
 
-# Memory
-docdict['memory'] = """
-memory : instance of :class:`joblib.Memory`, :obj:`str`, or \
-:class:`pathlib.Path`
-    Used to cache the masking process.
-    By default, no caching is done. If a :obj:`str` is given, it is the
-    path to the caching directory."""
+        - `dummy_classifier`: :class:`{dc} <sklearn.dummy.DummyClassifier>`.
+            .. code-block:: python
 
-# n_parcels
-docdict['n_parcels'] = """
-n_parcels : :obj:`int`, optional
-    Number of parcels to divide the data into.
-    Default=50."""
+                dummy = DummyClassifier(strategy='stratified',
+                                        random_state=0)
 
-# random_state
-docdict['random_state'] = """
-random_state : :obj:`int` or RandomState, optional
-    Pseudo-random number generator state used for random sampling."""
+"""
 
-# Memory_level
-memory_level = """
-memory_level : :obj:`int`, optional.
-    Rough estimator of the amount of memory used by caching. Higher value
-    means more memory for caching. Zero means no caching.
-    Default={}."""
-docdict['memory_level'] = memory_level.format(0)
-docdict['memory_level1'] = memory_level.format(1)
+# cmap
+docdict['cmap'] = """
+cmap : :class:`matplotlib.colors.Colormap`, or :obj:`str`, optional
+    The colormap to use. Either a string which is a name of
+    a matplotlib colormap, or a matplotlib colormap object."""
 
-# n_jobs
-n_jobs = """
-n_jobs : :obj:`int`, optional.
-    The number of CPUs to use to do the computation. -1 means 'all CPUs'.
-    Default={}."""
-docdict['n_jobs'] = n_jobs.format("1")
-docdict['n_jobs_all'] = n_jobs.format("-1")
+# colorbar
+docdict['colorbar'] = """
+colorbar : :obj:`bool`, optional
+    If ``True``, display a colorbar on the right of the plots."""
 
-# img
-docdict['img'] = """
-img : Niimg-like object
-    See :ref:`extracting_data`.
-"""
+# connected
+docdict['connected'] = """
+connected : :obj:`bool`, optional
+    If connected is True, only the largest connect component is kept."""
 
-# imgs
-docdict['imgs'] = """
-imgs : :obj:`list` of Niimg-like objects
-    See :ref:`extracting_data`.
-"""
 
 # confounds
 docdict['confounds'] = """
@@ -316,26 +198,6 @@
     shape: list of (number of scans, number of confounds)
 """
 
-# sample_mask
-docdict['sample_mask'] = """
-sample_mask : Any type compatible with numpy-array indexing, optional
-    shape: (number of scans - number of volumes removed, )
-    Masks the niimgs along time/fourth dimension to perform scrubbing
-    (remove volumes with high motion) and/or non-steady-state volumes.
-    This parameter is passed to :func:`nilearn.signal.clean`.
-"""
-
-# kwargs for Maskers
-docdict['masker_kwargs'] = """
-kwargs : dict
-    Keyword arguments to be passed to functions called within the masker.
-    Kwargs prefixed with ``'clean__'`` will be passed to
-    :func:`~nilearn.signal.clean`.
-    Within :func:`~nilearn.signal.clean`, kwargs prefixed with
-    ``'butterworth__'`` will be passed to the Butterworth filter
-    (i.e., ``clean__butterworth__``).
-"""
-
 # cut_coords
 docdict['cut_coords'] = """
 cut_coords : None, a :obj:`tuple` of :obj:`float`, or :obj:`int`, optional
@@ -359,29 +221,36 @@
 
 """
 
-# output_file
-docdict['output_file'] = """
-output_file : :obj:`str`, or None, optional
-    The name of an image file to export the plot to. Valid extensions
-    are .png, .pdf, .svg. If ``output_file`` is not None, the plot
-    is saved to a file, and the display is closed."""
+# darkness
+docdict['darkness'] = """
+darkness : :obj:`float` between 0 and 1, optional
+    Specifying the darkness of the background image:
 
-# extractor / extract_type
-docdict['extractor'] = """
-extractor : {'local_regions', 'connected_components'}, optional
-    This option can take two values:
+        - '1' indicates that the original values of the background are used
+        - '.5' indicates that the background values are reduced by half
+          before being applied.
 
-        - 'connected_components': each component/region in the image is
-          extracted automatically by labelling each region based upon the
-          presence of unique features in their respective regions.
+"""
 
-        - 'local_regions': each component/region is extracted based on
-          their maximum peak value to define a seed marker and then using
-          random walker segmentation algorithm on these markers for region
-          separation.
+# data_dir
+docdict['data_dir'] = """
+data_dir : :obj:`pathlib.Path` or :obj:`str`, optional
+    Path where data should be downloaded. By default,
+    files are downloaded in home directory."""
 
-    Default='local_regions'."""
-docdict['extract_type'] = docdict['extractor']
+# detrend
+docdict['detrend'] = """
+detrend : :obj:`bool`, optional
+    Whether to detrend signals or not."""
+
+# dimming factor
+docdict['dim'] = """
+dim : :obj:`float`, or 'auto', optional
+    Dimming factor applied to background image. By default, automatic
+    heuristics are applied based upon the background image intensity.
+    Accepted float values, where a typical span is between -2 and 2
+    (-2 = increase contrast; 2 = decrease contrast), but larger values
+    can be used for a more pronounced effect. 0 means no dimming."""
 
 # display_mode
 docdict['display_mode'] = """
@@ -401,157 +270,79 @@
 
     Default='ortho'."""
 
-# figure
-docdict['figure'] = """
-figure : :obj:`int`, or :class:`matplotlib.figure.Figure`, or None,  optional
-    Matplotlib figure used or its number. If ``None`` is given, a
-    new figure is created."""
-
-# axes
-docdict['axes'] = """
-axes : :class:`matplotlib.axes.Axes`, or 4 tuple\
-of :obj:`float`: (xmin, ymin, width, height), optional
-    The axes, or the coordinates, in matplotlib figure
-    space, of the axes used to display the plot.
-    If ``None``, the complete figure is used."""
-
-# title
-docdict['title'] = """
-title : :obj:`str`, or None, optional
-    The title displayed on the figure.
-    Default=None."""
-
-# threshold
-docdict['threshold'] = """
-threshold : a number, None, or 'auto', optional
-    If ``None`` is given, the image is not thresholded.
-    If a number is given, it is used to threshold the image:
-    values below the threshold (in absolute value) are plotted
-    as transparent. If 'auto' is given, the threshold is determined
-    magically by analysis of the image.
-"""
-
-# annotate
-docdict['annotate'] = """
-annotate : :obj:`bool`, optional
-    If ``annotate`` is ``True``, positions and left/right annotation
-    are added to the plot. Default=True."""
-
 # draw_cross
 docdict['draw_cross'] = """
 draw_cross : :obj:`bool`, optional
     If ``draw_cross`` is ``True``, a cross is drawn on the plot to indicate
     the cut position. Default=True."""
 
-# black_bg
-docdict['black_bg'] = """
-black_bg : :obj:`bool`, or 'auto', optional
-    If ``True``, the background of the image is set to be black.
-    If you wish to save figures with a black background, you
-    will need to pass facecolor='k', edgecolor='k'
-    to :func:`matplotlib.pyplot.savefig`."""
-
-# colorbar
-docdict['colorbar'] = """
-colorbar : :obj:`bool`, optional
-    If ``True``, display a colorbar on the right of the plots."""
-
-# symmetric_cbar
-docdict['symmetric_cbar'] = """
-symmetric_cbar : :obj:`bool`, or 'auto', optional
-    Specifies whether the colorbar should range from ``-vmax`` to ``vmax``
-    or from ``vmin`` to ``vmax``. Setting to 'auto' will select the latter
-    if the range of the whole image is either positive or negative.
-
-    .. note::
-
-        The colormap will always range from ``-vmax`` to ``vmax``.
-
-"""
-
-# cbar_tick_format
-docdict['cbar_tick_format'] = """
-cbar_tick_format : :obj:`str`, optional
-    Controls how to format the tick labels of the colorbar.
-    Ex: use "%%.2g" to display using scientific notation."""
+# ensure_finite
+docdict['ensure_finite'] = """
+ensure_finite : :obj:`bool`, optional
+    If True, the non-finite values (NANs and infs) found in the data
+    will be replaced by zeros."""
 
-# bg_img
-docdict['bg_img'] = """
-bg_img : Niimg-like object, optional
-    See :ref:`extracting_data`.
-    The background image to plot on top of.
-"""
+# extractor / extract_type
+docdict['extractor'] = """
+extractor : {'local_regions', 'connected_components'}, optional
+    This option can take two values:
 
-# vmin
-docdict['vmin'] = """
-vmin : :obj:`float`, optional
-    Lower bound of the colormap. If ``None``, the min of the image is used.
-    Passed to :func:`matplotlib.pyplot.imshow`.
-"""
+        - 'connected_components': each component/region in the image is
+          extracted automatically by labelling each region based upon the
+          presence of unique features in their respective regions.
 
-# vmax
-docdict['vmax'] = """
-vmax : :obj:`float`, optional
-    Upper bound of the colormap. If ``None``, the max of the image is used.
-    Passed to :func:`matplotlib.pyplot.imshow`.
-"""
+        - 'local_regions': each component/region is extracted based on
+          their maximum peak value to define a seed marker and then using
+          random walker segmentation algorithm on these markers for region
+          separation.
 
-# bg_vmin
-docdict['bg_vmin'] = """
-bg_vmin : :obj:`float`, optional
-    vmin for ``bg_img``."""
+    Default='local_regions'."""
+docdict['extract_type'] = docdict['extractor']
 
-# bg_vmax
-docdict['bg_vmax'] = """
-bg_vmin : :obj:`float`, optional
-    vmax for ``bg_img``."""
+# figure
+docdict['figure'] = """
+figure : :obj:`int`, or :class:`matplotlib.figure.Figure`, or None,  optional
+    Matplotlib figure used or its number. If ``None`` is given, a
+    new figure is created."""
 
-# resampling_interpolation
-docdict['resampling_interpolation'] = """
-resampling_interpolation : :obj:`str`, optional
-    Interpolation to use when resampling the image to
-    the destination space. Can be:
+# fsaverage options
+docdict['fsaverage_options'] = """
 
-        - "continuous": use 3rd-order spline interpolation
-        - "nearest": use nearest-neighbor mapping.
+        - 'fsaverage3': the low-resolution fsaverage3 mesh (642 nodes)
+        - 'fsaverage4': the low-resolution fsaverage4 mesh (2562 nodes)
+        - 'fsaverage5': the low-resolution fsaverage5 mesh (10242 nodes)
+        - 'fsaverage6': the medium-resolution fsaverage6 mesh (40962 nodes)
+        - 'fsaverage7': same as 'fsaverage'
+        - 'fsaverage': the high-resolution fsaverage mesh (163842 nodes)
 
             .. note::
-
-                "nearest" is faster but can be noisier in some cases.
+                The high-resolution fsaverage will result in more computation
+                time and memory usage
 
 """
 
-# cmap
-docdict['cmap'] = """
-cmap : :class:`matplotlib.colors.Colormap`, or :obj:`str`, optional
-    The colormap to use. Either a string which is a name of
-    a matplotlib colormap, or a matplotlib colormap object."""
-
-# Dimming factor
-docdict['dim'] = """
-dim : :obj:`float`, or 'auto', optional
-    Dimming factor applied to background image. By default, automatic
-    heuristics are applied based upon the background image intensity.
-    Accepted float values, where a typical span is between -2 and 2
-    (-2 = increase contrast; 2 = decrease contrast), but larger values
-    can be used for a more pronounced effect. 0 means no dimming."""
-
-# avg_method
-docdict['avg_method'] = """
-avg_method : {'mean', 'median', 'min', 'max', custom function}, optional
-    How to average vertex values to derive the face value:
+# fwhm
+docdict['fwhm'] = """
+fwhm : scalar, :class:`numpy.ndarray`, or :obj:`tuple`, or :obj:`list`,\
+or 'fast' or None, optional
+    Smoothing strength, as a :term:`full-width at half maximum<FWHM>`,
+    in millimeters:
 
-        - ``mean``: results in smooth boundaries
-        - ``median``: results in sharp boundaries
-        - ``min`` or ``max``: for sparse matrices
-        - ``custom function``: You can also pass a custom function
-          which will be executed though :func:`numpy.apply_along_axis`.
-          Here is an example of a custom function:
+        - If a nonzero scalar is given, width is identical in all 3 directions.
+        - If a :class:`numpy.ndarray`, :obj:`tuple`, or :obj:`list` is given,
+          it must have 3 elements, giving the :term:`FWHM` along each axis.
+          If any of the elements is zero or None, smoothing is not performed
+          along that axis.
+        - If `fwhm='fast'`, a fast smoothing will be performed with a filter
+          [0.2, 1, 0.2] in each direction and a normalisation to preserve the
+          local average value.
+        - If ``fwhm`` is None, no filtering is performed (useful when just
+          removal of non-finite values is needed).
 
-            .. code-block:: python
+    .. note::
 
-                def custom_function(vertices):
-                    return vertices[0] * vertices[1] * vertices[2]
+        In corner case situations, `fwhm` is simply kept to None when `fwhm`
+        is specified as `fwhm=0`.
 
 """
 
@@ -562,54 +353,15 @@ def custom_function(vertices):
 
 # hemispheres
 docdict['hemispheres'] = """
-hemispheres : list of :obj:`str`, optional
+hemispheres : :obj:`list` of :obj:`str`, optional
     Hemispheres to display. Default=['left', 'right']."""
 
-# view
-docdict['view'] = """
-view : :obj:`str` or a pair of :obj:`float`, optional.
-    If a string, must be in {'lateral', 'medial', 'dorsal', 'ventral',\
-    'anterior', 'posterior'}.
-    If a sequence, must be a pair (elev, azim) of float
-    angles in degrees that will manually set a custom view.
-    E.g., view=[270.0, 90.0] or view=(0.0, -180.0).
-    View of the surface that is rendered.
-    Default='lateral'.
-
-"""
-
-# bg_on_data
-docdict['bg_on_data'] = r"""
-bg_on_data : :obj:`bool`, optional
-    If ``True`` and a ``bg_map`` is specified,
-    the ``surf_data`` data is multiplied by the background
-    image, so that e.g. sulcal depth is jointly visible with ``surf_data``.
-    Otherwise, the background image will only be visible where there
-    is no surface data (either because ``surf_data`` contains ``nan``\s
-    or because is was thresholded).
-
-        .. note::
-            This non-uniformly changes the surf_data values according
-            to e.g the sulcal depth.
-
-"""
-
-# darkness
-docdict['darkness'] = """
-darkness : :obj:`float` between 0 and 1, optional
-    Specifying the darkness of the background image:
-
-        - '1' indicates that the original values of the background are used
-        - '.5' indicates that the background values are reduced by half
-          before being applied.
-
-"""
 
-# linewidth
-docdict['linewidths'] = """
-linewidths : :obj:`float`, optional
-    Set the boundary thickness of the contours.
-    Only reflects when ``view_type=contours``."""
+# high_pass
+docdict['high_pass'] = """
+high_pass : :obj:`float`, optional
+    High cutoff frequency in Hertz. If specified, signals below this
+    frequency will be filtered out. Default=None."""
 
 # hrf_model
 docdict['hrf_model'] = """
@@ -659,140 +411,334 @@ def custom_function(vertices):
         are orthogonalized wrt the main one.
 
 """
-# fsaverage options
-docdict['fsaverage_options'] = """
 
-        - 'fsaverage3': the low-resolution fsaverage3 mesh (642 nodes)
-        - 'fsaverage4': the low-resolution fsaverage4 mesh (2562 nodes)
-        - 'fsaverage5': the low-resolution fsaverage5 mesh (10242 nodes)
-        - 'fsaverage6': the medium-resolution fsaverage6 mesh (40962 nodes)
-        - 'fsaverage7': same as 'fsaverage'
-        - 'fsaverage': the high-resolution fsaverage mesh (163842 nodes)
+# img
+docdict['img'] = """
+img : Niimg-like object
+    See :ref:`extracting_data`.
+"""
+
+# imgs
+docdict['imgs'] = """
+imgs : :obj:`list` of Niimg-like objects
+    See :ref:`extracting_data`.
+"""
+
+# legacy_format
+docdict['legacy_format'] = """
+legacy_format : :obj:`bool`, optional
+    If set to ``True``, the fetcher will return recarrays. Otherwise,
+    it will return pandas dataframes.
+    Default=True."""
+
+# linewidth
+docdict['linewidths'] = """
+linewidths : :obj:`float`, optional
+    Set the boundary thickness of the contours.
+    Only reflects when ``view_type=contours``."""
+
+# low_pass
+docdict['low_pass'] = """
+low_pass : :obj:`float` or None, optional
+    Low cutoff frequency in Hertz. If specified, signals above this
+    frequency will be filtered out. If None, no low-pass filtering
+    will be performed. Default=None."""
+
+# lower_cutoff
+docdict['lower_cutoff'] = """
+lower_cutoff : :obj:`float`, optional
+    Lower fraction of the histogram to be discarded."""
+
+# mask_img
+docdict['mask_img'] = """
+mask_img : Niimg-like object
+    Object used for masking the data."""
+
+# mask_strategy
+docdict["mask_strategy"] = """
+mask_strategy : {'background', 'epi', 'whole-brain-template',\
+'gm-template', 'wm-template'}, optional
+    The strategy used to compute the mask:
+
+        - 'background': Use this option if your images present
+          a clear homogeneous background.
+        - 'epi': Use this option if your images are raw EPI images
+        - 'whole-brain-template': This will extract the whole-brain
+          part of your data by resampling the MNI152 brain mask for
+          your data's field of view.
+
+            .. note::
+                This option is equivalent to the previous 'template' option
+                which is now deprecated.
+
+        - 'gm-template': This will extract the gray matter part of your
+          data by resampling the corresponding MNI152 template for your
+          data's field of view.
+
+            .. versionadded:: 0.8.1
+
+        - 'wm-template': This will extract the white matter part of your
+          data by resampling the corresponding MNI152 template for your
+          data's field of view.
+
+            .. versionadded:: 0.8.1
+
+"""
+
+# mask_type
+docdict['mask_type'] = """
+mask_type : {'whole-brain', 'gm', 'wm'}, optional
+    Type of mask to be computed:
+
+        - 'whole-brain': Computes the whole-brain mask.
+        - 'gm': Computes the grey-matter mask.
+        - 'wm': Computes the white-matter mask.
+
+    Default = 'whole-brain'.
+
+"""
+
+# kwargs for Maskers
+docdict['masker_kwargs'] = """
+kwargs : dict
+    Keyword arguments to be passed to functions called within the masker.
+    Kwargs prefixed with ``'clean__'`` will be passed to
+    :func:`~nilearn.signal.clean`.
+    Within :func:`~nilearn.signal.clean`, kwargs prefixed with
+    ``'butterworth__'`` will be passed to the Butterworth filter
+    (i.e., ``clean__butterworth__``).
+"""
+
+# memory
+docdict['memory'] = """
+memory : instance of :class:`joblib.Memory`, :obj:`str`, or \
+:class:`pathlib.Path`
+    Used to cache the masking process.
+    By default, no caching is done. If a :obj:`str` is given, it is the
+    path to the caching directory."""
+
+# memory_level
+memory_level = """
+memory_level : :obj:`int`, optional.
+    Rough estimator of the amount of memory used by caching. Higher value
+    means more memory for caching. Zero means no caching.
+    Default={}."""
+docdict['memory_level'] = memory_level.format(0)
+docdict['memory_level1'] = memory_level.format(1)
+
+# n_jobs
+n_jobs = """
+n_jobs : :obj:`int`, optional.
+    The number of CPUs to use to do the computation. -1 means 'all CPUs'.
+    Default={}."""
+docdict['n_jobs'] = n_jobs.format("1")
+docdict['n_jobs_all'] = n_jobs.format("-1")
+
+# n_parcels
+docdict['n_parcels'] = """
+n_parcels : :obj:`int`, optional
+    Number of parcels to divide the data into.
+    Default=50."""
+
+# opening
+docdict['opening'] = """
+opening : :obj:`bool` or :obj:`int`, optional
+    This parameter determines whether a morphological
+    :term:`opening<Opening>` is performed, to keep only large structures.
+    This step is useful to remove parts of the skull that might have been
+    included. ``opening`` can be:
+
+        - A boolean : If False, no :term:`opening<Opening>` is performed.
+          If True, it is equivalent to ``opening=1``.
+        - An integer `n`: The :term:`opening<Opening>` is performed via `n`
+          :term:`erosions<Erosion>` (see :func:`scipy.ndimage.binary_erosion`).
+          The largest connected component is then estimated if ``connected`` is
+          set to True, and 2`n` :term:`dilation<Dilation>` operations are
+          performed (see :func:`scipy.ndimage.binary_dilation`) followed by
+          `n` :term:`erosions<Erosion>`. This corresponds to 1
+          :term:`opening<Opening>` operation of order `n` followed by a
+          :term:`closing<Closing>` operator of order `n`.
+
+    .. note::
 
-            .. note::
-                The high-resolution fsaverage will result in more computation
-                time and memory usage
+        Turning off :term:`opening<Opening>` (``opening=False``) will also
+        prevent any smoothing applied to the image during the mask computation.
 
 """
 
-# Classifiers
-base_url = "https://scikit-learn.org/stable/modules/generated/sklearn"
-svc = "Linear support vector classifier"
-logistic = "Logistic regression"
-rc = "Ridge classifier"
-dc = "Dummy classifier with stratified strategy"
-SKLEARN_LINKS = {
-    'svc': f"{base_url}.svm.SVC.html",
-    'logistic': f"{base_url}.linear_model.LogisticRegression.html",
-    'ridge_classifier': f"{base_url}.linear_model.RidgeClassifierCV.html",
-    'dummy_classifier': f"{base_url}.dummy.DummyClassifier.html",
-    'ridge': f"{base_url}.linear_model.RidgeCV.html",
-    'svr': f"{base_url}.svm.SVR.html",
-    'dummy_regressor': f"{base_url}.dummy.DummyRegressor.html",
-}
+# output_file
+docdict['output_file'] = """
+output_file : :obj:`str`, or None, optional
+    The name of an image file to export the plot to. Valid extensions
+    are .png, .pdf, .svg. If ``output_file`` is not None, the plot
+    is saved to a file, and the display is closed."""
 
-docdict['classifier_options'] = f"""
+# random_state
+docdict['random_state'] = """
+random_state : :obj:`int` or RandomState, optional
+    Pseudo-random number generator state used for random sampling."""
+
+# regressor_options
+docdict['regressor_options'] = """
 
-        - `svc`: `{svc} <%(svc)s>`_ with L2 penalty.
+        - `ridge`: \
+            :class:`{Ridge regression} <sklearn.linear_model.RidgeCV>`.
             .. code-block:: python
 
-                svc = LinearSVC(penalty='l2',
-                                max_iter=1e4)
+                ridge = RidgeCV()
 
-        - `svc_l2`: `{svc} <%(svc)s>`_ with L2 penalty.
+        - `ridge_regressor`: \
+            :class:`{Ridge regression} <sklearn.linear_model.RidgeCV>`.
             .. note::
-                Same as option `svc`.
+                Same option as `ridge`.
 
-        - `svc_l1`: `{svc} <%(svc)s>`_ with L1 penalty.
+        - `svr`: :class:`{Support vector regression} <sklearn.svm.SVR>`.
             .. code-block:: python
 
-                svc_l1 = LinearSVC(penalty='l1',
-                                   dual=False,
-                                   max_iter=1e4)
+                svr = SVR(kernel='linear',
+                          max_iter=1e4)
 
-        - `logistic`: `{logistic} <%(logistic)s>`_ with L2 penalty.
+        - `dummy_regressor`: \
+            :class:`{Dummy regressor} <sklearn.dummy.DummyRegressor>`.
             .. code-block:: python
 
-                logistic = LogisticRegression(penalty='l2',
-                                              solver='liblinear')
-
-        - `logistic_l1`: `{logistic} <%(logistic)s>`_ with L1 penalty.
-            .. code-block:: python
+                dummy = DummyRegressor(strategy='mean')
 
-                logistic_l1 = LogisticRegression(penalty='l1',
-                                                 solver='liblinear')
+"""
 
-        - `logistic_l2`: `{logistic} <%(logistic)s>`_ with L2 penalty
-            .. note::
-                Same as option `logistic`.
+# resampling_interpolation
+docdict['resampling_interpolation'] = """
+resampling_interpolation : :obj:`str`, optional
+    Interpolation to use when resampling the image to
+    the destination space. Can be:
 
-        - `ridge_classifier`: `{rc} <%(ridge_classifier)s>`_.
-            .. code-block:: python
+        - "continuous": use 3rd-order spline interpolation
+        - "nearest": use nearest-neighbor mapping.
 
-                ridge_classifier = RidgeClassifierCV()
+            .. note::
 
-        - `dummy_classifier`: `{dc} <%(dummy_classifier)s>`_.
-            .. code-block:: python
+                "nearest" is faster but can be noisier in some cases.
 
-                dummy = DummyClassifier(strategy='stratified',
-                                        random_state=0)
+"""
 
-""" % SKLEARN_LINKS
+# resume
+docdict['resume'] = """
+resume : :obj:`bool`, optional
+    Whether to resume download of a partly-downloaded file.
+    Default=True."""
 
-docdict['regressor_options'] = """
+# sample_mask
+docdict['sample_mask'] = """
+sample_mask : Any type compatible with numpy-array indexing, optional
+    shape: (number of scans - number of volumes removed, )
+    Masks the niimgs along time/fourth dimension to perform scrubbing
+    (remove volumes with high motion) and/or non-steady-state volumes.
+    This parameter is passed to :func:`nilearn.signal.clean`.
+"""
 
-        - `ridge`: `Ridge regression <%(ridge)s>`_.
-            .. code-block:: python
+# second_level_contrast
+docdict['second_level_contrast'] = """
+second_level_contrast : :obj:`str` or :class:`numpy.ndarray` of shape\
+(n_col), optional
+    Where ``n_col`` is the number of columns of the design matrix.
+    The string can be a formula compatible with :meth:`pandas.DataFrame.eval`.
+    Basically one can use the name of the conditions as they appear in the
+    design matrix of the fitted model combined with operators +- and combined
+    with numbers with operators +-`*`/. The default (None) is accepted if the
+    design matrix has a single column, in which case the only possible
+    contrast array((1)) is applied; when the design matrix has multiple
+    columns, an error is raised."""
 
-                ridge = RidgeCV()
+# second_level_input
+docdict['second_level_input'] = """
+second_level_input : :obj:`list` of \
+:class:`~nilearn.glm.first_level.FirstLevelModel` objects \
+or :class:`pandas.DataFrame` or :obj:`list` of Niimg-like objects.
 
-        - `ridge_regressor`: `Ridge regression <%(ridge)s>`_.
-            .. note::
-                Same option as `ridge`.
+    - Giving :class:`~nilearn.glm.first_level.FirstLevelModel` objects
+      will allow to easily compute the second level contrast of arbitrary first
+      level contrasts thanks to the ``first_level_contrast`` argument of
+      :meth:`~nilearn.glm.first_level.FirstLevelModel.compute_contrast`.
+      Effect size images will be computed for each model to contrast at
+      the second level.
+    - If a :class:`~pandas.DataFrame`, then it has to contain
+      ``subject_label``, ``map_name`` and ``effects_map_path``. It can
+      contain multiple maps that would be selected during contrast estimation
+      with the argument ``first_level_contrast`` of
+      :meth:`~nilearn.glm.first_level.FirstLevelModel.compute_contrast`.
+      The :class:`~pandas.DataFrame` will be sorted based on
+      the ``subject_label`` column to avoid order inconsistencies when
+      extracting the maps. So the rows of the automatically computed
+      design matrix, if not provided, will correspond to the sorted
+      ``subject_label`` column.
+    - If a :obj:`list` of Niimg-like objects then this is taken
+      literally as Y for the model fit and ``design_matrix`` must be
+      provided.
 
-        - `svr`: `Support vector regression <%(svr)s>`_.
-            .. code-block:: python
+"""
 
-                svr = SVR(kernel='linear',
-                          max_iter=1e4)
+# smoothing_fwhm
+docdict['smoothing_fwhm'] = """
+smoothing_fwhm : :obj:`float`, optional.
+    If ``smoothing_fwhm`` is not ``None``, it gives
+    the :term:`full-width at half maximum<FWHM>` in millimeters
+    of the spatial smoothing to apply to the signal."""
 
-        - `dummy_regressor`: `Dummy regressor <%(dummy_regressor)s>`_.
-            .. code-block:: python
+# standardize
+standardize = """
+standardize : :obj:`bool`, optional.
+    If ``standardize`` is True, the data are centered and normed:
+    their mean is put to 0 and their variance is put to 1 in the
+    time dimension.
+    Default={}."""
+docdict['standardize'] = standardize.format('True')
+docdict['standardize_false'] = standardize.format('False')
 
-                dummy = DummyRegressor(strategy='mean')
+# standardize_confounds
+docdict['standardize_confounds'] = """
+standardize_confounds : :obj:`bool`, optional
+    If set to True, the confounds are z-scored: their mean is put
+    to 0 and their variance to 1 in the time dimension.
+    Default=True."""
 
-""" % SKLEARN_LINKS
+# symmetric_cbar
+docdict['symmetric_cbar'] = """
+symmetric_cbar : :obj:`bool`, or 'auto', optional
+    Specifies whether the colorbar should range from ``-vmax`` to ``vmax``
+    or from ``vmin`` to ``vmax``. Setting to 'auto' will select the latter
+    if the range of the whole image is either positive or negative.
 
-# mask_strategy
-docdict["mask_strategy"] = """
-mask_strategy : {'background', 'epi', 'whole-brain-template',\
-'gm-template', 'wm-template'}, optional
-    The strategy used to compute the mask:
+    .. note::
 
-        - 'background': Use this option if your images present
-          a clear homogeneous background.
-        - 'epi': Use this option if your images are raw EPI images
-        - 'whole-brain-template': This will extract the whole-brain
-          part of your data by resampling the MNI152 brain mask for
-          your data's field of view.
+        The colormap will always range from ``-vmax`` to ``vmax``.
 
-            .. note::
-                This option is equivalent to the previous 'template' option
-                which is now deprecated.
+"""
 
-        - 'gm-template': This will extract the gray matter part of your
-          data by resampling the corresponding MNI152 template for your
-          data's field of view.
+# t_r
+docdict['t_r'] = """
+t_r : :obj:`float` or None, optional
+    Repetition time, in seconds (sampling period).
+    Set to ``None`` if not provided.
+    Default=None."""
 
-            .. versionadded:: 0.8.1
+# target_affine
+docdict['target_affine'] = """
+target_affine : :class:`numpy.ndarray`, optional.
+    If specified, the image is resampled corresponding to this new affine.
+    ``target_affine`` can be a 3x3 or a 4x4 matrix.
+    Default=None."""
 
-        - 'wm-template': This will extract the white matter part of your
-          data by resampling the corresponding MNI152 template for your
-          data's field of view.
+# target_shape
+docdict['target_shape'] = """
+target_shape : :obj:`tuple` or :obj:`list`, optional.
+    If specified, the image will be resized to match this new shape.
+    ``len(target_shape)`` must be equal to 3.
 
-            .. versionadded:: 0.8.1
+    .. note::
+        If ``target_shape`` is specified, a ``target_affine`` of shape
+        ``(4, 4)`` must also be given.
 
-"""
+    Default=None."""
 
 # templateflow
 docdict["templateflow"] = """
@@ -803,6 +749,72 @@ def custom_function(vertices):
     (https://www.templateflow.org/).
 """
 
+# threshold
+docdict['threshold'] = """
+threshold : a number, None, or 'auto', optional
+    If ``None`` is given, the image is not thresholded.
+    If a number is given, it is used to threshold the image:
+    values below the threshold (in absolute value) are plotted
+    as transparent. If 'auto' is given, the threshold is determined
+    magically by analysis of the image.
+"""
+
+# title
+docdict['title'] = """
+title : :obj:`str`, or None, optional
+    The title displayed on the figure.
+    Default=None."""
+
+# upper_cutoff
+docdict['upper_cutoff'] = """
+upper_cutoff : :obj:`float`, optional
+    Upper fraction of the histogram to be discarded."""
+
+# url
+docdict['url'] = """
+url : :obj:`str`, optional
+    URL of file to download.
+    Override download URL. Used for test only (or if you
+    setup a mirror of the data).
+    Default=None."""
+
+# verbose
+verbose = """
+verbose : :obj:`int`, optional
+    Verbosity level (0 means no message).
+    Default={}."""
+docdict['verbose'] = verbose.format(1)
+docdict['verbose0'] = verbose.format(0)
+
+# view
+docdict['view'] = """
+view : :obj:`str` or a pair of :obj:`float`, optional.
+    If a string, must be in {'lateral', 'medial', 'dorsal', 'ventral',\
+    'anterior', 'posterior'}.
+    If a sequence, must be a pair (elev, azim) of float
+    angles in degrees that will manually set a custom view.
+    E.g., view=[270.0, 90.0] or view=(0.0, -180.0).
+    View of the surface that is rendered.
+    Default='lateral'.
+
+"""
+
+# vmax
+docdict['vmax'] = """
+vmax : :obj:`float`, optional
+    Upper bound of the colormap. If ``None``, the max of the image is used.
+    Passed to :func:`matplotlib.pyplot.imshow`.
+"""
+
+# vmin
+docdict['vmin'] = """
+vmin : :obj:`float`, optional
+    Lower bound of the colormap. If ``None``, the min of the image is used.
+    Passed to :func:`matplotlib.pyplot.imshow`.
+"""
+
+##############################################################################
+
 docdict_indented = {}
 
 


Test patch: