From 5e87b5c7d66fd23e647214552f83faf24dccfec0 Mon Sep 17 00:00:00 2001
From: Neil Vaytet <neil.vaytet@ess.eu>
Date: Tue, 16 Apr 2024 14:09:59 +0200
Subject: [PATCH 1/5] add examples back in figure docstrings and deprecate
 TriCutTool

---
 src/plopp/graphics/imageview.py     | 14 ++++++++++++++
 src/plopp/graphics/lineview.py      | 22 ++++++++++++++++++++++
 src/plopp/graphics/scatter3dview.py | 14 ++++++++++++++
 src/plopp/graphics/scatterview.py   | 14 ++++++++++++++
 src/plopp/widgets/cut3d.py          |  2 ++
 5 files changed, 66 insertions(+)

diff --git a/src/plopp/graphics/imageview.py b/src/plopp/graphics/imageview.py
index 51d5864f..a23922f2 100644
--- a/src/plopp/graphics/imageview.py
+++ b/src/plopp/graphics/imageview.py
@@ -119,6 +119,20 @@ def imagefigure(*args, **kwargs):
     Create a figure to represent two-dimensional data from one or more graph node(s).
 
     .. versionadded:: 24.04.0
+
+    Examples
+    --------
+    Create an input node and attach an ``imagefigure`` as a view:
+
+      >>> da = pp.data.data2d()
+      >>> in_node = pp.Node(da)
+      >>> fig = pp.imagefigure(in_node)
+
+    With a customization argument to make the color scale logarithmic:
+
+      >>> da = pp.data.data2d()
+      >>> in_node = pp.Node(da)
+      >>> fig = pp.imagefigure(in_node, norm='log')
     """
 
     return backends.figure2d(ImageView, *args, **kwargs)
diff --git a/src/plopp/graphics/lineview.py b/src/plopp/graphics/lineview.py
index 6d771dce..7f55da33 100644
--- a/src/plopp/graphics/lineview.py
+++ b/src/plopp/graphics/lineview.py
@@ -122,6 +122,28 @@ def linefigure(*args, **kwargs):
     Create a figure to represent one-dimensional data from one or more graph node(s).
 
     .. versionadded:: 24.04.0
+
+    Examples
+    --------
+    Create an input node and attach a ``linefigure`` as a view:
+
+      >>> da = pp.data.data1d()
+      >>> in_node = pp.Node(da)
+      >>> fig = pp.linefigure(in_node)
+
+    Visualize two data arrays on the same figure:
+
+      >>> a = pp.data.data1d()
+      >>> b = 3 * a
+      >>> a_node = pp.Node(a)
+      >>> b_node = pp.Node(b)
+      >>> fig = pp.linefigure(a_node, b_node)
+
+    With a customization argument to make the vertical scale logarithmic:
+
+      >>> da = pp.data.data1d()
+      >>> in_node = pp.Node(da)
+      >>> fig = pp.linefigure(in_node, norm='log')
     """
 
     return backends.figure2d(LineView, *args, **kwargs)
diff --git a/src/plopp/graphics/scatter3dview.py b/src/plopp/graphics/scatter3dview.py
index 1976df8e..5c95483a 100644
--- a/src/plopp/graphics/scatter3dview.py
+++ b/src/plopp/graphics/scatter3dview.py
@@ -192,6 +192,20 @@ def scatter3dfigure(*args, **kwargs):
     Create a figure to represent three-dimensional data from one or more graph node(s).
 
     .. versionadded:: 24.04.0
+
+    Examples
+    --------
+    Create an input node and attach a ``scatter3dfigure`` as a view:
+
+      >>> da = pp.data.scatter()
+      >>> in_node = pp.Node(da)
+      >>> fig = pp.scatter3dfigure(in_node)
+
+    With a customization argument to make the color scale logarithmic:
+
+      >>> da = pp.data.scatter()
+      >>> in_node = pp.Node(da)
+      >>> fig = pp.scatter3dfigure(in_node, norm='log')
     """
 
     return backends.figure3d(Scatter3dView, *args, **kwargs)
diff --git a/src/plopp/graphics/scatterview.py b/src/plopp/graphics/scatterview.py
index 6965b7a3..ee541715 100644
--- a/src/plopp/graphics/scatterview.py
+++ b/src/plopp/graphics/scatterview.py
@@ -94,6 +94,20 @@ def scatterfigure(*args, **kwargs):
     Create a figure to represent scatter data from one or more graph node(s).
 
     .. versionadded:: 24.04.0
+
+    Examples
+    --------
+    Create an input node and attach a ``scatterfigure`` as a view:
+
+      >>> da = pp.data.scatter()
+      >>> in_node = pp.Node(da)
+      >>> fig = pp.scatterfigure(in_node)
+
+    A scatter figure with a color bar (using the data values for the color scale):
+
+      >>> da = pp.data.scatter()
+      >>> in_node = pp.Node(da)
+      >>> fig = pp.scatterfigure(in_node, cbar=True)
     """
 
     return backends.figure2d(ScatterView, *args, **kwargs)
diff --git a/src/plopp/widgets/cut3d.py b/src/plopp/widgets/cut3d.py
index 60d00d21..a467a46d 100644
--- a/src/plopp/widgets/cut3d.py
+++ b/src/plopp/widgets/cut3d.py
@@ -225,6 +225,8 @@ class TriCutTool(ipw.HBox):
     A collection of :class:`Cut3dTool` to make spatial cuts in the X, Y, and Z
     directions on a three-dimensional scatter plot.
 
+    .. deprecated:: v24.04.0
+
     Parameters
     ----------
     fig:

From 7b4c547b24e4c174100e8ca2c9610b81ff3c7f20 Mon Sep 17 00:00:00 2001
From: Neil Vaytet <neil.vaytet@ess.eu>
Date: Tue, 16 Apr 2024 14:52:32 +0200
Subject: [PATCH 2/5] add deprecated decorator

---
 src/plopp/graphics/figure.py | 21 ++++-----------------
 src/plopp/utils.py           | 27 +++++++++++++++++++++++++++
 src/plopp/widgets/cut3d.py   |  3 +++
 3 files changed, 34 insertions(+), 17 deletions(-)
 create mode 100644 src/plopp/utils.py

diff --git a/src/plopp/graphics/figure.py b/src/plopp/graphics/figure.py
index b7d1e0a0..5ed923c8 100644
--- a/src/plopp/graphics/figure.py
+++ b/src/plopp/graphics/figure.py
@@ -1,22 +1,13 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
 
-import warnings
 from typing import Literal
 
 from .. import backends
-from ..core.typing import VisibleDeprecationWarning
-
-
-def _warn_deprecated(func_name: str, new_func_name: str):
-    warnings.warn(
-        f'The function `{func_name}` is deprecated and will be removed in a future '
-        f'version. Use `{new_func_name}` instead.',
-        VisibleDeprecationWarning,
-        stacklevel=2,
-    )
+from ..utils import deprecated
 
 
+@deprecated('Use ``linefigure`` instead.')
 def figure1d(*args, style: Literal['line'] = 'line', **kwargs):
     """
     Create a figure to represent one-dimensional data from one or more graph node(s).
@@ -53,8 +44,6 @@ def figure1d(*args, style: Literal['line'] = 'line', **kwargs):
       >>> fig = pp.figure1d(in_node, norm='log')
     """
 
-    _warn_deprecated('figure1d', 'linefigure')
-
     if style == 'line':
         from .lineview import LineView
 
@@ -63,6 +52,7 @@ def figure1d(*args, style: Literal['line'] = 'line', **kwargs):
     raise ValueError(f'Unsupported style={style} for figure1d.')
 
 
+@deprecated('Use ``imagefigure`` instead.')
 def figure2d(*args, style: Literal['image'] = 'image', **kwargs):
     """
     Create a figure to represent two-dimensional data from a graph node.
@@ -91,8 +81,6 @@ def figure2d(*args, style: Literal['image'] = 'image', **kwargs):
       >>> fig = pp.figure2d(in_node, norm='log')
     """
 
-    _warn_deprecated('figure2d', 'imagefigure')
-
     if style == 'image':
         from .imageview import ImageView
 
@@ -101,6 +89,7 @@ def figure2d(*args, style: Literal['image'] = 'image', **kwargs):
     raise ValueError(f'Unsupported style={style} for figure2d.')
 
 
+@deprecated('Use ``scatter3dfigure`` instead.')
 def figure3d(*args, style: Literal['scatter'] = 'scatter', **kwargs):
     """
     Create a figure to represent three-dimensional data from a graph node.
@@ -129,8 +118,6 @@ def figure3d(*args, style: Literal['scatter'] = 'scatter', **kwargs):
       >>> fig = pp.figure3d(in_node, norm='log')
     """
 
-    _warn_deprecated('figure3d', 'scatter3dfigure')
-
     if style == 'scatter':
         from .scatter3dview import Scatter3dView
 
diff --git a/src/plopp/utils.py b/src/plopp/utils.py
new file mode 100644
index 00000000..761e9722
--- /dev/null
+++ b/src/plopp/utils.py
@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+
+import warnings
+from typing import Callable
+
+from .core.typing import VisibleDeprecationWarning
+
+
+def deprecated(message: str = '') -> Callable:
+
+    def decorator(function: Callable) -> Callable:
+
+        def wrapper(*args, **kwargs):
+            warnings.warn(
+                f'{function.__name__} is deprecated. {message}',
+                VisibleDeprecationWarning,
+                stacklevel=2,
+            )
+            return function(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+__all__ = ['deprecated']
diff --git a/src/plopp/widgets/cut3d.py b/src/plopp/widgets/cut3d.py
index a467a46d..994b0c73 100644
--- a/src/plopp/widgets/cut3d.py
+++ b/src/plopp/widgets/cut3d.py
@@ -10,11 +10,13 @@
 import scipp as sc
 
 from ..core import View, node
+from ..utils import deprecated
 from .debounce import debounce
 from .style import BUTTON_LAYOUT
 from .tools import PlusMinusTool
 
 
+@deprecated("Use ``Clip3dTool`` instead.")
 class Cut3dTool(ipw.HBox):
     """
     A tool that provides a slider to extract a plane of points in a three-dimensional
@@ -220,6 +222,7 @@ def decrease_thickness(self):
         self._add_cut()
 
 
+@deprecated("Use ``ClippingPlanes`` instead.")
 class TriCutTool(ipw.HBox):
     """
     A collection of :class:`Cut3dTool` to make spatial cuts in the X, Y, and Z

From 242ffe3712b8fba9f7989bfd6baae44f4e45ec33 Mon Sep 17 00:00:00 2001
From: Neil Vaytet <neil.vaytet@ess.eu>
Date: Tue, 16 Apr 2024 14:53:01 +0200
Subject: [PATCH 3/5] black

---
 src/plopp/utils.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/plopp/utils.py b/src/plopp/utils.py
index 761e9722..1a8320c0 100644
--- a/src/plopp/utils.py
+++ b/src/plopp/utils.py
@@ -8,9 +8,7 @@
 
 
 def deprecated(message: str = '') -> Callable:
-
     def decorator(function: Callable) -> Callable:
-
         def wrapper(*args, **kwargs):
             warnings.warn(
                 f'{function.__name__} is deprecated. {message}',

From c86d90062489d7a5408ee01b59cf81fc53324fe8 Mon Sep 17 00:00:00 2001
From: Neil Vaytet <neil.vaytet@ess.eu>
Date: Tue, 16 Apr 2024 15:02:25 +0200
Subject: [PATCH 4/5] filter warnings in tests

---
 pyproject.toml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/pyproject.toml b/pyproject.toml
index 9e87da2c..73f7b83a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -62,6 +62,8 @@ filterwarnings = [
   'ignore:Passing unrecognized arguments to super:DeprecationWarning',
   'ignore:Jupyter is migrating its paths:DeprecationWarning',
   'ignore:setDaemon\(\) is deprecated, set the daemon attribute instead:DeprecationWarning',
+  'ignore:TriCutTool is deprecated::',
+  'ignore:Cut3dTool is deprecated::',
 ]
 
 [tool.bandit]

From 8b5ea7cdf735093f6e6e25a97762edfd3e712591 Mon Sep 17 00:00:00 2001
From: Neil Vaytet <neil.vaytet@ess.eu>
Date: Tue, 16 Apr 2024 15:09:49 +0200
Subject: [PATCH 5/5] add functools wraps to preserve docstring and signature

---
 src/plopp/utils.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/plopp/utils.py b/src/plopp/utils.py
index 1a8320c0..9a842ade 100644
--- a/src/plopp/utils.py
+++ b/src/plopp/utils.py
@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
 
+import functools
 import warnings
 from typing import Callable
 
@@ -9,6 +10,7 @@
 
 def deprecated(message: str = '') -> Callable:
     def decorator(function: Callable) -> Callable:
+        @functools.wraps(function)
         def wrapper(*args, **kwargs):
             warnings.warn(
                 f'{function.__name__} is deprecated. {message}',