Merge pull request #324 from scipp/docs-tweaks

Small docs fixes

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]

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
 

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)

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)

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)

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)

src/plopp/utils.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+
+import functools
+import warnings
+from typing import Callable
+
+from .core.typing import VisibleDeprecationWarning
+
+
+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}',
+                VisibleDeprecationWarning,
+                stacklevel=2,
+            )
+            return function(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+__all__ = ['deprecated']

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,11 +222,14 @@ 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
     directions on a three-dimensional scatter plot.
 
+    .. deprecated:: v24.04.0
+
     Parameters
     ----------
     fig: