add features section to docs for Graphics

kushalkolar · web-flow · commit c50beb6d0889 · 2023-05-21T08:56:56.000-04:00
diff --git a/docs/source/api/graphic_features.rst b/docs/source/api/graphic_features.rst
@@ -0,0 +1,15 @@
+Features
+********
+
+.. autoclass:: fastplotlib.graphics.features.ImageDataFeature
+    :members:
+    :inherited-members: 
+    :exclude-members: __init__
+    :no-undoc-members:
+    
+.. autoclass:: fastplotlib.graphics.features.ImageCmapFeature
+    :members:
+    :inherited-members: 
+    :exclude-members: __init__
+    :no-undoc-members:
+    
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -17,12 +17,11 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = ["sphinx.ext.napoleon", "sphinx.ext.autodoc"]
-autodoc_typehints = "description"
 
 templates_path = ['_templates']
 exclude_patterns = []
 
-
+napoleon_custom_sections = ['Features']
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -32,9 +31,12 @@
 
 html_static_path = ['_static']
 
-autodoc_member_order = 'bysource'
+autodoc_member_order = 'groupwise'
 autoclass_content = "both"
 
+autodoc_typehints = "description"
+autodoc_typehints_description_target = "documented_params"
+
 def _setup_navbar_side_toctree(app: Any):
 
     def add_class_toctree_function(app: Any, pagename: Any, templatename: Any, context: Any, doctree: Any):
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -14,6 +14,7 @@ Welcome to fastplotlib's documentation!
    Subplot <api/subplot>
    Gridplot <api/gridplot>
    Graphics <api/graphics>
+   Graphic Features <api/graphic_features>
    Selectors <api/selectors>
    Widgets <api/widgets>
 
diff --git a/fastplotlib/graphics/features/_base.py b/fastplotlib/graphics/features/_base.py
@@ -3,6 +3,7 @@
 from warnings import warn
 from typing import *
 import weakref
+from dataclasses import dataclass
 
 import numpy as np
 from pygfx import Buffer, Texture
@@ -40,13 +41,20 @@ def to_gpu_supported_dtype(array):
 
 class FeatureEvent:
     """
-    type: <feature_name>, example: "colors"
+    Dataclass that holds feature event information. Has ``type`` and ``pick_info`` attributes.
+
+    Attributes
+    ----------
+    type: str, example "colors"
+
     pick_info: dict in the form:
-        {
-            "index": indices where feature data was changed, ``range`` object or List[int],
-            "world_object": world object the feature belongs to,
-            "new_values": the new values
-        }
+     ============== =======================================================================
+      index          indices where feature data was changed, ``range`` object or List[int]
+     ============== =======================================================================
+      world_object   world object the feature belongs to
+      new_data       the new data for this feature
+     ============== =======================================================================
+
     """
     def __init__(self, type: str, pick_info: dict):
         self.type = type
@@ -60,18 +68,15 @@ def __repr__(self):
 
 class GraphicFeature(ABC):
     def __init__(self, parent, data: Any, collection_index: int = None):
-        """
-
-        Parameters
-        ----------
-        parent
-
-        data: Any
-
-        collection_index: int
-            if part of a collection, index of this graphic within the collection
-
-        """
+        # not shown as a docstring so it doesn't show up in the docs
+        # Parameters
+        # ----------
+        # parent
+        #
+        # data: Any
+        #
+        # collection_index: int
+        #     if part of a collection, index of this graphic within the collection
         self._parent = weakref.proxy(parent)
 
         self._data = to_gpu_supported_dtype(data)
@@ -119,6 +124,15 @@ def add_event_handler(self, handler: callable):
         self._event_handlers.append(handler)
 
     def remove_event_handler(self, handler: callable):
+        """
+        Remove a registered event handler
+
+        Parameters
+        ----------
+        handler: callable
+            event handler to remove
+
+        """
         if handler not in self._event_handlers:
             raise KeyError(f"event handler {handler} not registered.")
 
@@ -254,7 +268,7 @@ def cleanup_array_slice(key: np.ndarray, upper_bound) -> np.ndarray:
 
 
 class GraphicFeatureIndexable(GraphicFeature):
-    """And indexable Graphic Feature, colors, data, sizes etc."""
+    """An indexable Graphic Feature, colors, data, sizes etc."""
 
     def _set(self, value):
         value = self._parse_set_value(value)
diff --git a/fastplotlib/graphics/image.py b/fastplotlib/graphics/image.py
@@ -8,7 +8,7 @@
 
 from ._base import Graphic, Interaction, PreviouslyModifiedData
 from .selectors import LinearSelector, LinearRegionSelector
-from .features import ImageCmapFeature, ImageDataFeature, HeatmapDataFeature, HeatmapCmapFeature
+from .features import ImageCmapFeature, ImageDataFeature, HeatmapDataFeature, HeatmapCmapFeature, PresentFeature
 from .features._base import to_gpu_supported_dtype
 from ..utils import quick_min_max
 
@@ -160,6 +160,7 @@ class ImageGraphic(Graphic, Interaction, _ImageHeatmapSelectorsMixin):
     feature_events = (
         "data",
         "cmap",
+        "present"
     )
 
     def __init__(
@@ -199,6 +200,18 @@ def __init__(
         kwargs:
             additional keyword arguments passed to Graphic
 
+        Features
+        --------
+
+        **data**: :class:`.ImageDataFeature`
+            Manages the data buffer displayed in the ImageGraphic
+
+        **cmap**: :class:`.ImageCmapFeature`
+            Manages the colormap
+
+        **present**: :class:`.PresentFeature`
+            Control the presence of the Graphic in the scene
+
         Examples
         --------
         .. code-block:: python
