Colormaps: fixed/comp. documentation

PierreRaybaut · PierreRaybaut · commit 915e16f24f82 · 2024-02-06T14:32:16.000+01:00
diff --git a/doc/dev/guiqwt_to_plotpy.csv b/doc/dev/guiqwt_to_plotpy.csv
@@ -31,7 +31,7 @@ guiqwt v4,plotpy v2,API changes
 ``guiqwt.pyplot``,``plotpy.pyplot``
 ``guiqwt.styles``,``plotpy.styles``
 ``guiqwt.tools``,``plotpy.tools``
-``guiqwt.colormap``,``plotpy.mathutils.colormap``
+``guiqwt.colormap``,``plotpy.mathutils.colormaps``
 ``guiqwt.geometry``,``plotpy.mathutils.geometry``
 ``guiqwt.qthelpers.exec_image_save_dialog``,``plotpy.widgets.imagefile.exec_image_save_dialog``
 ``guiqwt.qthelpers.exec_image_open_dialog``,``plotpy.widgets.imagefile.exec_image_open_dialog``
diff --git a/doc/dev/v1_to_v2.csv b/doc/dev/v1_to_v2.csv
@@ -18,7 +18,7 @@ plotpy v1,plotpy v2 (and v1.99+)
 ``.gui.widgets.histogram.ContrastAdjustment``,``.panels.contrastadjustment.ContrastAdjustment``
 ``.gui.widgets.io``,``.io``
 ``.gui.widgets.io.eliminate_outliers``,*removed*
-``.gui.widgets.colormap``,``.mathutils.colormap``
+``.gui.widgets.colormap``,``.mathutils.colormaps``
 ``.gui.widgets.debug``,*removed*
 ``.gui.widgets.debug.buttons_to_str``,``.events.buttons_to_str``
 ``.gui.widgets.debug.evt_type_to_str``,``.events.evt_type_to_str``
diff --git a/doc/features/colormapmanager.rst b/doc/features/colormapmanager.rst
@@ -0,0 +1 @@
+.. automodule:: plotpy.widgets.colormap
diff --git a/doc/features/index.rst b/doc/features/index.rst
@@ -47,6 +47,7 @@ Plot widgets with integrated plot manager:
    tools/index
    styles/index
    panels/index
+   colormapmanager
    fit
    pyplot
    resizedialog
diff --git a/doc/features/mathutils/colormap.rst b/doc/features/mathutils/colormap.rst
diff --git a/doc/features/mathutils/colormaps.rst b/doc/features/mathutils/colormaps.rst
@@ -0,0 +1 @@
+.. automodule:: plotpy.mathutils.colormaps
diff --git a/doc/features/mathutils/index.rst b/doc/features/mathutils/index.rst
@@ -7,4 +7,4 @@ Utilities
 
    geometry
    scaler
-   colormap
+   colormaps
diff --git a/doc/features/tools/reference.rst b/doc/features/tools/reference.rst
@@ -3,6 +3,8 @@ Reference
 
 .. autoclass:: plotpy.tools.GuiTool
    :members:
+.. autoclass:: plotpy.tools.GuiToolT
+   :members:
 .. autoclass:: plotpy.tools.InteractiveTool
    :members:
 .. autoclass:: plotpy.tools.CommandTool
diff --git a/plotpy/items/curve/base.py b/plotpy/items/curve/base.py
@@ -257,9 +257,11 @@ def __setstate__(self, state: tuple) -> None:
 
     def serialize(
         self,
-        writer: guidata.dataset.io.HDF5Writer
-        | guidata.dataset.io.INIWriter
-        | guidata.dataset.io.JSONWriter,
+        writer: (
+            guidata.dataset.io.HDF5Writer
+            | guidata.dataset.io.INIWriter
+            | guidata.dataset.io.JSONWriter
+        ),
     ) -> None:
         """Serialize object to HDF5 writer
 
@@ -274,9 +276,11 @@ def serialize(
 
     def deserialize(
         self,
-        reader: guidata.dataset.io.HDF5Reader
-        | guidata.dataset.io.INIReader
-        | guidata.dataset.io.JSONReader,
+        reader: (
+            guidata.dataset.io.HDF5Reader
+            | guidata.dataset.io.INIReader
+            | guidata.dataset.io.JSONReader
+        ),
     ) -> None:
         """Deserialize object from HDF5 reader
 
@@ -389,8 +393,8 @@ def set_data(self, x: np.ndarray, y: np.ndarray) -> None:
             x: X data
             y: Y data
             decimated_data: Set to True if CurveItem X and Y arrays are already set and
-            this method is called to update decimated data (i.e. only update 1/N value
-            with N set in CurveItem.param.decimation).
+             this method is called to update decimated data (i.e. only update 1/N value
+             with N set in CurveItem.param.decimation).
         """
         self._x = np.array(x, copy=False)
         self._y = np.array(y, copy=False)
diff --git a/plotpy/mathutils/colormaps.py b/plotpy/mathutils/colormaps.py
@@ -4,9 +4,32 @@
 # (see plotpy/LICENSE for details)
 
 """
-This module provides utilities to interact with colormap. It provides functions
-to load/save colormaps from/to json files and to build icons representing the
-colormaps.
+Colormap functions
+------------------
+
+Overview
+^^^^^^^^
+
+The :py:mod:`.colormap` module contains definition of common colormaps and tools
+to manipulate and create them.
+
+The following functions are available:
+
+* :py:func:`.get_cmap`: get a colormap from its name
+* :py:func:`.cmap_exists`: check if a colormap exists
+* :py:func:`.add_cmap`: add a colormap to the list of available colormaps
+* :py:func:`.build_icon_from_cmap`: build an icon representing the colormap
+* :py:func:`.build_icon_from_cmap_name`: build an icon representing the colormap
+  from its name
+
+Reference
+^^^^^^^^^
+
+.. autofunction:: get_cmap
+.. autofunction:: cmap_exists
+.. autofunction:: add_cmap
+.. autofunction:: build_icon_from_cmap
+.. autofunction:: build_icon_from_cmap_name
 """
 
 from __future__ import annotations
diff --git a/plotpy/plot/manager.py b/plotpy/plot/manager.py
@@ -60,11 +60,7 @@
 
     from qwt import QwtPlotCanvas, QwtScaleDiv
 
-    from plotpy.panels.base import PanelWidget
-    from plotpy.panels.contrastadjustment import ContrastAdjustment
-    from plotpy.panels.csection import XCrossSection, YCrossSection
-    from plotpy.panels.itemlist import PlotItemList
-    from plotpy.tools.base import GuiTool, GuiToolT
+    from plotpy.panels import ContrastAdjustment, PanelWidget, PlotItemList
 
 
 class DefaultPlotID:
diff --git a/plotpy/tools/__init__.py b/plotpy/tools/__init__.py
@@ -17,6 +17,7 @@
     CommandTool,
     DefaultToolbarID,
     GuiTool,
+    GuiToolT,
     InteractiveTool,
     PanelTool,
     RectangularActionTool,
diff --git a/plotpy/widgets/colormap/__init__.py b/plotpy/widgets/colormap/__init__.py
@@ -1 +1,16 @@
 # -*- coding: utf-8 -*-
+
+"""
+colormap
+========
+
+The `colormap` module contains definition of common colormaps and tools
+to manipulate and create them.
+
+.. automodule:: plotpy.widgets.colormap.widget
+    :members:
+.. automodule:: plotpy.widgets.colormap.editor
+    :members:
+.. automodule:: plotpy.widgets.colormap.manager
+    :members:
+"""
diff --git a/plotpy/widgets/colormap/editor.py b/plotpy/widgets/colormap/editor.py
@@ -4,9 +4,20 @@
 # (see plotpy/LICENSE for details)
 
 """
+Colormap editor
+---------------
+
 This module provides a more complete colormap editor widget than the one provided
 by ColorMapWidget (plotpy/widgets/colormap_widget.py). It allows to edit a colormap
 by changing its color stops (add/delete/move/change color).
+
+Reference
+~~~~~~~~~
+
+.. autoclass:: ColorPickDataSet
+    :members:
+.. autoclass:: ColorMapEditor
+    :members:
 """
 
 from __future__ import annotations
@@ -102,11 +113,11 @@ class ColorMapEditor(QW.QWidget):
         cmap_width: Cmap size in pixels. Defaults to 400.
         cmap_height: Cmap height in pixels. Defaults to 50.
         color1: First color of the colormap. If None, color blue is used. Ignored if
-        argument 'colormap' is used. Defaults to None.
+         argument 'colormap' is used. Defaults to None.
         color2: Last color of the colormap. If None, color yellow is used.Ignored if
-        argument 'colormap' is used. Defaults to None
+         argument 'colormap' is used. Defaults to None
         colormap: An already initialized colormap to use in the widget.
-        Defaults to None.
+         Defaults to None.
     """
 
     def __init__(
diff --git a/plotpy/widgets/colormap/manager.py b/plotpy/widgets/colormap/manager.py
@@ -4,8 +4,20 @@
 # (see plotpy/LICENSE for details)
 
 """
+Colormap manager
+----------------
+
 This module provides a fully featured colormap manager widget and dialog window
 that allows to select, edit and save colormaps (existing or new).
+
+
+Reference
+~~~~~~~~~
+
+.. autoclass:: ColorMapNameEdit
+    :members:
+.. autoclass:: ColorMapManager
+    :members:
 """
 
 from __future__ import annotations
@@ -100,7 +112,7 @@ class ColorMapManager(QW.QDialog):
     Args:
         parent: parent QWidget. Defaults to None.
         active_colormap: name of the default colormap selected. If None or does not
-        exists, will defaults to the first colormap in the list. Defaults to None
+         *exists, will defaults to the first colormap in the list. Defaults to None
     """
 
     def __init__(
diff --git a/plotpy/widgets/colormap/widget.py b/plotpy/widgets/colormap/widget.py
@@ -4,8 +4,20 @@
 # (see plotpy/LICENSE for details)
 
 """
+Colormap widget
+---------------
+
 This module provides a basic widget to edit a colormap that contains a multi-slider
 and a colorap representation.
+
+
+Reference
+~~~~~~~~~
+
+.. autoclass:: EditableColormap
+    :members:
+.. autoclass:: ColorMapWidget
+    :members:
 """
 
 from __future__ import annotations
@@ -23,7 +35,10 @@
 from plotpy.config import _
 from plotpy.widgets.colormap._slider import QColorMapSlider
 
+#: Type variable for color types
 ColorTypeT = TypeVar("ColorTypeT", bound=Union[QG.QColor, int])
+
+#: Type for color initialization types
 QColorInitTypes = Union[
     QG.QColor, int, Tuple[int, int, int, int], str, QC.Qt.GlobalColor, None
 ]
@@ -36,9 +51,9 @@ class EditableColormap(QwtLinearColorMap):
     Args:
         *args: QwtLinearColorMap arguments
         name: Optional str name given to the colormap. Useful for the interactions
-        with the rest of PlotPy, notably with the gobal colormaps dictionaries
-        such as colormaps.ALL_COLORMAPS. If None, the colormap name will be set to
-        "temporary". Defaults to None.
+         with the rest of PlotPy, notably with the gobal colormaps dictionaries
+         such as colormaps.ALL_COLORMAPS. If None, the colormap name will be set to
+         "temporary". Defaults to None.
     """
 
     def __init__(self, *args, name: str | None = None) -> None:
@@ -155,7 +170,7 @@ def move_color_stop(
             stop_index: color stop index to move
             new_pos: new color stop position
             new_color: new color stop color. If None, will use the current stop color.
-            Defaults to None.
+             Defaults to None.
         """
         try:
             stop: ColorStop | None = self.stops[stop_index]
@@ -223,11 +238,11 @@ class ColorMapWidget(QW.QWidget):
         cmap_width: minimum width of the widget. Defaults to 400.
         cmap_height: minimum height of the colorbar. Defaults to 50.
         color1: first color. Ignored if the 'colormap' argument is used. If None,
-            default color is blue. Defaults to None.
+         default color is blue. Defaults to None.
         color2: second color. Ignored if the 'colormap' argument is used. If None,
-            default color is yellow. Defaults to None.
+         default color is yellow. Defaults to None.
         colormap: colormap instance. If None, color1 and color2 will be used
-            to create a new colormap. Defaults to None.
+         to create a new colormap. Defaults to None.
     """
 
     COLORMAP_CHANGED = QC.Signal()  # type: ignore
@@ -399,7 +414,7 @@ def edit_color_stop(
         Args:
             index: color stop index to mutate
             new_pos: new color stop position. If not set will remain the same.
-            Defaults to None.
+             Defaults to None.
             new_color: new color. If not set will remain the same. Defaults to None.
         """
         if new_pos is None:

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+.. automodule:: plotpy.widgets.colormap`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+.. automodule:: plotpy.mathutils.colormaps`