[MAINT] add warning to deprecate darkness

nilearn/plotting/surf_plotting.py

@@ -22,6 +22,8 @@
 from nilearn.surface import load_surf_data, load_surf_mesh, vol_to_surf
 from nilearn.surface.surface import _check_mesh
 
+from warnings import warn
+
 VALID_VIEWS = "anterior", "posterior", "medial", "lateral", "dorsal", "ventral"
 VALID_HEMISPHERES = "left", "right"
 
@@ -460,6 +462,12 @@
 
     if darkness is not None:
         bg_faces *= darkness
+        warn(
+            (
+                "The `darkness` parameter will be deprecated in release 0.13. "
+                "We recommend setting `darkness` to None"
+            )
+        )
 
     face_colors = plt.cm.gray_r(bg_faces)
 

nilearn/plotting/tests/test_surf_plotting.py

@@ -1105,3 +1105,18 @@ def test_compute_facecolors_matplotlib():
     assert not np.allclose(
         facecolors_manually_rescaled, facecolors_auto_normalized
     )
+
+    with pytest.warns(
+        UserWarning,
+        match=(
+            "The `darkness` parameter will be deprecated in release 0.13. "
+            "We recommend setting `darkness` to None"
+        ),
+    ):
+        facecolors_manually_rescaled = _compute_facecolors_matplotlib(
+            bg_map_scaled,
+            mesh[1],
+            len(mesh[0]),
+            0.5,
+            alpha,
+        )