Repository: nilearn/nilearn

Issue:
Renaming plotting.html_surface.one_mesh_info() and plotting.html_surface.full_brain_info()
This is a follow-up issue from #3173.

`plotting.html_surface.one_mesh_info()` and `plotting.html_surface.full_brain_info()` should be renamed to `plotting.html_surface._one_mesh_info()` and `plotting.html_surface._full_brain_info()` respectively so that it becomes explicit that they're not in the public API.


Discussion:
hi would you please assign me i would like to start contribute 
@alexisthual 

Resolving patch:
diff --git a/nilearn/plotting/html_surface.py b/nilearn/plotting/html_surface.py
--- a/nilearn/plotting/html_surface.py
+++ b/nilearn/plotting/html_surface.py
@@ -110,10 +110,11 @@ def _get_vertexcolor(surf_map, cmap, norm,
     return to_color_strings(vertex_colors)
 
 
-def one_mesh_info(surf_map, surf_mesh, threshold=None, cmap=cm.cold_hot,
-                  black_bg=False, bg_map=None, symmetric_cmap=True,
-                  bg_on_data=False, darkness=.7,
-                  vmax=None, vmin=None):
+def _one_mesh_info(
+        surf_map, surf_mesh, threshold=None, cmap=cm.cold_hot, black_bg=False,
+        bg_map=None, symmetric_cmap=True, bg_on_data=False, darkness=.7,
+        vmax=None, vmin=None
+):
     """Prepare info for plotting one surface map on a single mesh.
 
     This computes the dictionary that gets inserted in the web page,
@@ -138,6 +139,26 @@ def one_mesh_info(surf_map, surf_mesh, threshold=None, cmap=cm.cold_hot,
     return info
 
 
+def one_mesh_info(
+        surf_map, surf_mesh, threshold=None, cmap=cm.cold_hot, black_bg=False,
+        bg_map=None, symmetric_cmap=True, bg_on_data=False, darkness=.7,
+        vmax=None, vmin=None,
+):
+    """Deprecate public function. See _one_mesh_info."""
+    warn(
+        category=DeprecationWarning,
+        message="one_mesh_info is a private function and is renamed "
+        "to _one_mesh_info. Using the deprecated name will "
+        "raise an error in release 0.13",
+    )
+
+    return _one_mesh_info(surf_map, surf_mesh, threshold=threshold, cmap=cmap,
+                          black_bg=black_bg, bg_map=bg_map,
+                          symmetric_cmap=symmetric_cmap,
+                          bg_on_data=bg_on_data, darkness=darkness,
+                          vmax=vmax, vmin=vmin)
+
+
 def _check_mesh(mesh):
     if isinstance(mesh, str):
         return datasets.fetch_surf_fsaverage(mesh)
@@ -155,10 +176,10 @@ def _check_mesh(mesh):
     return mesh
 
 
-def full_brain_info(volume_img, mesh='fsaverage5', threshold=None,
-                    cmap=cm.cold_hot, black_bg=False, symmetric_cmap=True,
-                    bg_on_data=False, darkness=.7,
-                    vmax=None, vmin=None, vol_to_surf_kwargs={}):
+def _full_brain_info(volume_img, mesh='fsaverage5', threshold=None,
+                     cmap=cm.cold_hot, black_bg=False, symmetric_cmap=True,
+                     bg_on_data=False, darkness=.7,
+                     vmax=None, vmin=None, vol_to_surf_kwargs={}):
     """Project 3D map on cortex; prepare info to plot both hemispheres.
 
     This computes the dictionary that gets inserted in the web page,
@@ -199,6 +220,26 @@ def full_brain_info(volume_img, mesh='fsaverage5', threshold=None,
     return info
 
 
+def full_brain_info(volume_img, mesh='fsaverage5', threshold=None,
+                    cmap=cm.cold_hot, black_bg=False, symmetric_cmap=True,
+                    bg_on_data=False, darkness=.7,
+                    vmax=None, vmin=None, vol_to_surf_kwargs={}):
+    """Deprecate public function. See _full_brain_info."""
+    warn(
+        category=DeprecationWarning,
+        message="full_brain_info is a private function and is renamed to "
+        "_full_brain_info. Using the deprecated name will raise an error "
+        "in release 0.13",
+    )
+
+    return _full_brain_info(
+        volume_img, mesh=mesh, threshold=threshold, cmap=cmap,
+        black_bg=black_bg, symmetric_cmap=symmetric_cmap,
+        bg_on_data=bg_on_data, darkness=darkness, vmax=vmax, vmin=vmin,
+        vol_to_surf_kwargs=vol_to_surf_kwargs
+    )
+
+
 def _fill_html_template(info, embed_js=True):
     as_json = json.dumps(info)
     as_html = get_html_template('surface_plot_template.html').safe_substitute(
@@ -306,7 +347,7 @@ def view_img_on_surf(stat_map_img, surf_mesh='fsaverage5',
 
     """
     stat_map_img = check_niimg_3d(stat_map_img)
-    info = full_brain_info(
+    info = _full_brain_info(
         volume_img=stat_map_img, mesh=surf_mesh, threshold=threshold,
         cmap=cmap, black_bg=black_bg, vmax=vmax, vmin=vmin,
         bg_on_data=bg_on_data, darkness=darkness,
@@ -426,7 +467,7 @@ def view_surf(surf_mesh, surf_map=None, bg_map=None, threshold=None,
             surf_mesh, surf_map)
     if bg_map is not None:
         _, bg_map = surface.check_mesh_and_data(surf_mesh, bg_map)
-    info = one_mesh_info(
+    info = _one_mesh_info(
         surf_map=surf_map, surf_mesh=surf_mesh, threshold=threshold,
         cmap=cmap, black_bg=black_bg, bg_map=bg_map,
         bg_on_data=bg_on_data, darkness=darkness,
diff --git a/nilearn/surface/surface.py b/nilearn/surface/surface.py
--- a/nilearn/surface/surface.py
+++ b/nilearn/surface/surface.py
@@ -966,8 +966,8 @@ def _check_mesh(mesh):
     """Check that mesh data is either a :obj:`str`, \
         or a :obj:`dict` with sufficient entries.
 
-    Used by :func:`plotting.surf_plotting.plot_img_on_surf` and
-    :func:`plotting.html_surface.full_brain_info`
+    Used by plotting.surf_plotting.plot_img_on_surf and
+    plotting.html_surface._full_brain_info
 
     """
     if isinstance(mesh, str):


Test patch:
diff --git a/nilearn/plotting/tests/test_html_surface.py b/nilearn/plotting/tests/test_html_surface.py
--- a/nilearn/plotting/tests/test_html_surface.py
+++ b/nilearn/plotting/tests/test_html_surface.py
@@ -93,7 +93,7 @@ def test_one_mesh_info():
     mesh = fsaverage["pial_left"]
     surf_map = surface.load_surf_data(fsaverage["sulc_left"])
     mesh = surface.load_surf_mesh(mesh)
-    info = html_surface.one_mesh_info(
+    info = html_surface._one_mesh_info(
         surf_map, mesh, '90%', black_bg=True,
         bg_map=surf_map)
     assert {'_x', '_y', '_z', '_i', '_j', '_k'}.issubset(
@@ -109,11 +109,19 @@ def test_one_mesh_info():
     assert not info['full_brain_mesh']
     check_colors(info['colorscale'])
 
+    with pytest.warns(
+        DeprecationWarning,
+        match="one_mesh_info is a private function and is renamed "
+        "to _one_mesh_info. Using the deprecated name will "
+        "raise an error in release 0.13",
+    ):
+        html_surface.one_mesh_info(surf_map, mesh)
+
 
 def test_full_brain_info():
     surfaces = datasets.fetch_surf_fsaverage()
     img = _get_img()
-    info = html_surface.full_brain_info(img, surfaces)
+    info = html_surface._full_brain_info(img, surfaces)
     check_colors(info['colorscale'])
     assert {'pial_left', 'pial_right',
             'inflated_left', 'inflated_right',
@@ -131,20 +139,28 @@ def test_full_brain_info():
         assert len(decode(
             info[f'pial_{hemi}']['_j'], '<i4')) == len(mesh[1])
 
+    with pytest.warns(
+        DeprecationWarning,
+        match="full_brain_info is a private function and is renamed to "
+        "_full_brain_info. Using the deprecated name will raise an error "
+        "in release 0.13",
+    ):
+        html_surface.full_brain_info(img)
+
 
 def test_fill_html_template():
     fsaverage = fetch_surf_fsaverage()
     mesh = surface.load_surf_mesh(fsaverage['pial_right'])
     surf_map = mesh[0][:, 0]
     img = _get_img()
-    info = html_surface.one_mesh_info(
+    info = html_surface._one_mesh_info(
         surf_map, fsaverage['pial_right'], '90%', black_bg=True,
         bg_map=fsaverage['sulc_right'])
     info["title"] = None
     html = html_surface._fill_html_template(info, embed_js=False)
     check_html(html)
     assert "jquery.min.js" in html.html
-    info = html_surface.full_brain_info(img)
+    info = html_surface._full_brain_info(img)
     info["title"] = None
     html = html_surface._fill_html_template(info)
     check_html(html)