[WIP] apply black to docs

.pre-commit-config.yaml

@@ -48,10 +48,11 @@ repos:
     -   id: check-case-conflict
     -   id: check-json
     -   id: check-merge-conflict
+    -   id: check-toml
     -   id: check-yaml
     -   id: end-of-file-fixer
+    -   id: mixed-line-ending
     -   id: trailing-whitespace
-    -   id: check-toml
 
 -   repo: https://github.com/pycqa/isort
     rev: 5.12.0
@@ -70,12 +71,25 @@ repos:
     -   id: pyupgrade
         args: [--py36-plus]
 
--   repo: https://github.com/psf/black
+-   repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.10.0
+    hooks:
+    -   id: rst-directive-colons
+    -   id: rst-inline-touching-normal
+
+-   repo: https://github.com/psf/black-pre-commit-mirror
     rev: 23.9.1
     hooks:
     -   id: black
         args: [--config, pyproject.toml]
 
+-   repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.16.0
+    hooks:
+    -   id: blacken-docs
+        additional_dependencies:
+        -   black==23.9.1
+
 -   repo: https://github.com/codespell-project/codespell
     rev: v2.2.5
     hooks:

CONTRIBUTING.rst

@@ -314,35 +314,36 @@ See the examples below:
 .. code-block:: python
 
       def good(x, y=1, z=None):
-      """Show how parameters are documented.
+          """Show how parameters are documented.
 
-      Parameters
-      ----------
-      x : :obj:`int`
-            X
+          Parameters
+          ----------
+          x : :obj:`int`
+                X
 
-      y : :obj:`int`, default=1
-            Note that "default=1" is preferred to "Defaults to 1".
+          y : :obj:`int`, default=1
+                Note that "default=1" is preferred to "Defaults to 1".
 
-      z : :obj:`str`, default=None
+          z : :obj:`str`, default=None
+
+          """
 
-      """
 
       def bad(x, y=1, z=None):
-      """Show how parameters should not be documented.
+          """Show how parameters should not be documented.
 
-      Parameters
-      ----------
-      x :
-            The type of X is not described
+          Parameters
+          ----------
+          x :
+                The type of X is not described
 
-      y : :obj:`int`
-            The default value of y is not described.
+          y : :obj:`int`
+                The default value of y is not described.
 
-      z : :obj:`str`
-            Defaults=None.
-            The default value should be described after the type.
-      """
+          z : :obj:`str`
+                Defaults=None.
+                The default value should be described after the type.
+          """
 
 Additionally, we consider it best practice to write modular functions;
 i.e., functions should preferably be relatively short and do *one* thing.
@@ -386,48 +387,52 @@ Code inside ``maskers._validation.py``:
 
 .. code-block:: python
 
-      import numpy as np # not part of the public API
+      import numpy as np  # not part of the public API
 
-      __all__ = ["check_mask_img", "ValidationError"] # all symbols in the public API
+      __all__ = ["check_mask_img", "ValidationError"]  # all symbols in the public API
 
 
       def check_mask_img(mask_img):
-      """Public API of _validation module
+          """Public API of _validation module
+
+          can be used in nifti_masker module
+          but not the image module (which cannot import maskers._validation),
+          unless maskers/__init__.py imports it and lists it in __all__
+          to make it part of the maskers module's public API
+          """
+
 
-      can be used in nifti_masker module
-      but not the image module (which cannot import maskers._validation),
-      unless maskers/__init__.py imports it and lists it in __all__
-      to make it part of the maskers module's public API
-      """
       return _check_mask_shape(mask_img) and _check_mask_values(mask_img)
 
 
       def _check_mask_shape(mask_img):
-      """Private internal of _validation, cannot be used in nifti_masker"""
+          """Private internal of _validation, cannot be used in nifti_masker"""
 
 
       def _check_mask_values(mask_img):
-      """Private internal of _validation, cannot be used in nifti_masker"""
+          """Private internal of _validation, cannot be used in nifti_masker"""
 
 
       class ValidationError(Exception):
-      """Public API of _validation module"""
+          """Public API of _validation module"""
 
 
       class _Validator:
-      """Private internal of the _validation module"""
+          """Private internal of the _validation module"""
+
 
       def validate(self, img):
-            """Public API of _Validator"""
+          """Public API of _Validator"""
+
 
       def _validate_shape(self, img):
-            """Private internal of the _Validator class.
+          """Private internal of the _Validator class.
 
-            As we don't use the double leading underscore in nilearn we cannot
-            infer from the name alone if it is considered to be exposed to
-            subclasses or not.
+          As we don't use the double leading underscore in nilearn we cannot
+          infer from the name alone if it is considered to be exposed to
+          subclasses or not.
 
-            """
+          """
 
 ..
       Source: Jerome Dockes https://github.com/nilearn/nilearn/issues/3628#issuecomment-1515211711
@@ -515,21 +520,21 @@ like in the following examples:
 .. code-block:: python
 
       def test_something():
-            # set up
-            rng = np.random.default_rng(0)
-            my_number = rng.normal()
+          # set up
+          rng = np.random.default_rng(0)
+          my_number = rng.normal()
 
-            # the rest of the test
+          # the rest of the test
 
 You can also use the `rng` fixture.
 
 .. code-block:: python
 
       def test_something(rng):
-            # set up
-            my_number = rng.normal()
+          # set up
+          my_number = rng.normal()
 
-            # the rest of the test
+          # the rest of the test
 
 Documentation
 -------------

README.rst

@@ -14,6 +14,9 @@
     :target: https://codecov.io/gh/nilearn/nilearn
     :alt: Coverage Status
 
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+
 .. image:: http://img.shields.io/twitter/follow/nilearn.svg
     :target: https://twitter.com/nilearn
     :alt: Twitter
@@ -29,7 +32,6 @@
 
 
 
-
 nilearn
 =======
 

doc/building_blocks/manual_pipeline.rst

@@ -149,6 +149,7 @@ order to learn simple parameters from it, such as its shape:
     # about. Here we use standardizing of the data, as it is often important
     # for decoding
     from nilearn.maskers import NiftiMasker
+
     masker = NiftiMasker(mask_img=mask_filename, standardize=True)
 
     # We give the masker a filename and retrieve a 2D array ready
@@ -223,8 +224,9 @@ discriminating weight.
 
     from nilearn.plotting import plot_stat_map, show
 
-    plot_stat_map(coef_img, bg_img=haxby_dataset.anat[0],
-                  title="SVM weights", display_mode="yx")
+    plot_stat_map(
+        coef_img, bg_img=haxby_dataset.anat[0], title="SVM weights", display_mode="yx"
+    )
 
     show()
 

nilearn/_utils/docs.py

@@ -138,8 +138,7 @@ def custom_function(vertices):
         - `svc`: :class:`{svc} <sklearn.svm.LinearSVC>` with L2 penalty.
             .. code-block:: python
 
-                svc = LinearSVC(penalty="l2",
-                                max_iter=1e4)
+                svc = LinearSVC(penalty="l2", max_iter=1e4)
 
         - `svc_l2`: :class:`{svc} <sklearn.svm.LinearSVC>` with L2 penalty.
             .. note::
@@ -148,25 +147,21 @@ def custom_function(vertices):
         - `svc_l1`: :class:`{svc} <sklearn.svm.LinearSVC>` with L1 penalty.
             .. code-block:: python
 
-                svc_l1 = LinearSVC(penalty="l1",
-                                   dual=False,
-                                   max_iter=1e4)
+                svc_l1 = LinearSVC(penalty="l1", dual=False, max_iter=1e4)
 
         - `logistic`: \
             :class:`{logistic} <sklearn.linear_model.LogisticRegressionCV>` \
             with L2 penalty.
             .. code-block:: python
 
-                logistic = LogisticRegression(penalty="l2",
-                                              solver="liblinear")
+                logistic = LogisticRegression(penalty="l2", solver="liblinear")
 
         - `logistic_l1`: \
             :class:`{logistic} <sklearn.linear_model.LogisticRegressionCV>` \
             with L1 penalty.
             .. code-block:: python
 
-                logistic_l1 = LogisticRegression(penalty="l1",
-                                                 solver="liblinear")
+                logistic_l1 = LogisticRegression(penalty="l1", solver="liblinear")  # noqa
 
         - `logistic_l2`: \
             :class:`{logistic} <sklearn.linear_model.LogisticRegressionCV>` \
@@ -183,8 +178,7 @@ def custom_function(vertices):
         - `dummy_classifier`: :class:`{dc} <sklearn.dummy.DummyClassifier>`.
             .. code-block:: python
 
-                dummy = DummyClassifier(strategy="stratified",
-                                        random_state=0)
+                dummy = DummyClassifier(strategy="stratified", random_state=0)
 
 """
 
@@ -721,8 +715,7 @@ def custom_function(vertices):
         - `svr`: :class:`{Support vector regression} <sklearn.svm.SVR>`.
             .. code-block:: python
 
-                svr = SVR(kernel="linear",
-                          max_iter=1e4)
+                svr = SVR(kernel="linear", max_iter=1e4)
 
         - `lasso`: \
             :class:`{Lasso regression} <sklearn.linear_model.LassoCV>`.
@@ -739,7 +732,7 @@ def custom_function(vertices):
             :class:`{Dummy regressor} <sklearn.dummy.DummyRegressor>`.
             .. code-block:: python
 
-                dummy = DummyRegressor(strategy='mean')
+                dummy = DummyRegressor(strategy="mean")
 
 """
 

nilearn/datasets/atlas.py

@@ -1205,15 +1205,15 @@ def fetch_atlas_aal(
     .. code-block:: python
 
         # This should print 'Lingual_L'
-        data.labels[data.indices.index('5021')]
+        data.labels[data.indices.index("5021")]
 
     Conversely, to get the region ID corresponding to the label
     "Precentral_L", you should do:
 
     .. code-block:: python
 
         # This should print '2001'
-        data.indices[data.labels.index('Precentral_L')]
+        data.indices[data.labels.index("Precentral_L")]
 
     Parameters
     ----------
@@ -1966,7 +1966,7 @@ def fetch_atlas_pauli_2017(version="prob", data_dir=None, verbose=1):
                     .. code-block:: python
 
                         # Prepend background label
-                        data.labels.insert(0, 'Background')
+                        data.labels.insert(0, "Background")
 
                     Or be careful that the indexing should be offset by one:
 
@@ -1975,7 +1975,7 @@ def fetch_atlas_pauli_2017(version="prob", data_dir=None, verbose=1):
                         # Get region ID of label 'NAC' when 'background' was
                         # not added to the list of labels:
                         # idx_nac should be equal to 3:
-                        idx_nac = data.labels.index('NAC') + 1
+                        idx_nac = data.labels.index("NAC") + 1
 
             - 'description': :obj:`str`, short description of the atlas and
               some references.
@@ -2077,7 +2077,7 @@ def fetch_atlas_schaefer_2018(
                     .. code-block:: python
 
                         # Prepend background label
-                        data.labels = np.insert(data.labels, 0, 'Background')
+                        data.labels = np.insert(data.labels, 0, "Background")
 
                     Or be careful that the indexing should be offset by one:
 
@@ -2086,9 +2086,7 @@ def fetch_atlas_schaefer_2018(
                         # Get region ID of label '7Networks_LH_Vis_3' when
                         # 'Background' was not added to the list of labels:
                         # idx should be equal to 3:
-                        idx = np.where(
-                            data.labels == b'7Networks_LH_Vis_3'
-                        )[0] + 1
+                        idx = np.where(data.labels == b"7Networks_LH_Vis_3")[0] + 1