fastplotlib · kushalkolar · Jul 6, 2023 · Jul 6, 2023 · Jul 6, 2023 · Jul 6, 2023
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -15,6 +15,37 @@ on:
 
 jobs:
 
+  docs-build:
+    name: Docs
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+    - name: Install llvmpipe and lavapipe for offscreen canvas, and git lfs
+      run: |
+        sudo apt-get update -y -qq
+        sudo apt-get install --no-install-recommends -y libegl1-mesa libgl1-mesa-dri libxcb-xfixes0-dev mesa-vulkan-drivers git-lfs
+    - name: Install pandoc v3.14, nbsphinx complains about older pandoc versions
+      run: |
+        wget https://github.com/jgm/pandoc/releases/download/3.1.4/pandoc-3.1.4-1-amd64.deb
+        sudo apt-get install ./pandoc-3.1.4-1-amd64.deb
+    - name: Install dev dependencies
+      run: |
+        python -m pip install --upgrade pip
+        # remove pygfx from requirements, we install a specific commit of pygfx since both fpl and pygfx are fast evolving
+        sed -i "/pygfx/d" ./setup.py
+        pip install git+https://github.com/pygfx/pygfx.git@cf1da6c32223ba3cf7256982ce9b89c81b593076
+        pip install -e ".[notebook,docs,tests]"
+    - name: Build docs
+      run: |
+        cd docs
+        make html SPHINXOPTS="-W --keep-going"
+
   test-build:
     name: Test examples
     runs-on: ubuntu-latest
@@ -47,7 +78,7 @@ jobs:
         python -m pip install --upgrade pip
         # remove pygfx from requirements, we install a specific commit of pygfx since both fpl and pygfx are fast evolving
         sed -i "/pygfx/d" ./setup.py
-        pip install git+https://github.com/pygfx/pygfx.git@b63f22a1aa61993c32cd96895316cb8248a81e4d
+        pip install git+https://github.com/pygfx/pygfx.git@cf1da6c32223ba3cf7256982ce9b89c81b593076
         pip install -e ".["tests"]"
     - name: Show wgpu backend
       run:

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -10,7 +10,6 @@ build:
     - libxcb-xfixes0-dev
     - mesa-vulkan-drivers
     - libglfw3
-    - pandoc
   jobs:
     post_checkout:
       # Download and uncompress the binary
@@ -27,6 +26,9 @@ build:
       - ./git-lfs fetch
       # Make local files to have the real content on them
       - ./git-lfs checkout
+      # install newer pandoc else nbsphinx complains
+      - wget https://github.com/jgm/pandoc/releases/download/3.1.4/pandoc-3.1.4-1-amd64.deb
+      - sudo apt-get install ./pandoc-3.1.4-1-amd64.deb
     pre_install:
       - pip install git+https://github.com/pygfx/pygfx.git@main
 

diff --git a/docs/source/api/graphics/HistogramGraphic.rst b/docs/source/api/graphics/HistogramGraphic.rst
diff --git a/docs/source/api/graphics/index.rst b/docs/source/api/graphics/index.rst
@@ -7,7 +7,6 @@ Graphics
     ImageGraphic
     ScatterGraphic
     LineGraphic
-    HistogramGraphic
     HeatmapGraphic
     LineCollection
     LineStack

diff --git a/docs/source/api/layouts/gridplot.rst b/docs/source/api/layouts/gridplot.rst
@@ -20,6 +20,8 @@ Properties
 .. autosummary::
     :toctree: GridPlot_api
 
+    GridPlot.canvas
+    GridPlot.renderer
 
 Methods
 ~~~~~~~

diff --git a/docs/source/api/layouts/plot.rst b/docs/source/api/layouts/plot.rst
@@ -23,6 +23,7 @@ Properties
     Plot.camera
     Plot.canvas
     Plot.controller
+    Plot.docks
     Plot.graphics
     Plot.name
     Plot.parent
@@ -40,7 +41,6 @@ Methods
     Plot.add_animations
     Plot.add_graphic
     Plot.add_heatmap
-    Plot.add_histogram
     Plot.add_image
     Plot.add_line
     Plot.add_line_collection

diff --git a/docs/source/api/layouts/subplot.rst b/docs/source/api/layouts/subplot.rst
@@ -23,6 +23,7 @@ Properties
     Subplot.camera
     Subplot.canvas
     Subplot.controller
+    Subplot.docks
     Subplot.graphics
     Subplot.name
     Subplot.parent
@@ -40,7 +41,6 @@ Methods
     Subplot.add_animations
     Subplot.add_graphic
     Subplot.add_heatmap
-    Subplot.add_histogram
     Subplot.add_image
     Subplot.add_line
     Subplot.add_line_collection

diff --git a/fastplotlib/graphics/__init__.py b/fastplotlib/graphics/__init__.py
@@ -1,4 +1,3 @@
-from .histogram import HistogramGraphic
 from .line import LineGraphic
 from .scatter import ScatterGraphic
 from .image import ImageGraphic, HeatmapGraphic
@@ -9,7 +8,6 @@
     "ImageGraphic",
     "ScatterGraphic",
     "LineGraphic",
-    "HistogramGraphic",
     "HeatmapGraphic",
     "LineCollection",
     "LineStack",

diff --git a/fastplotlib/graphics/_base.py b/fastplotlib/graphics/_base.py
@@ -75,27 +75,30 @@ def __init__(
     @property
     def world_object(self) -> WorldObject:
         """Associated pygfx WorldObject. Always returns a proxy, real object cannot be accessed directly."""
+        # We use weakref to simplify garbage collection
         return weakref.proxy(WORLD_OBJECTS[hex(id(self))])
 
     def _set_world_object(self, wo: WorldObject):
         WORLD_OBJECTS[hex(id(self))] = wo
 
     @property
     def position(self) -> np.ndarray:
-        """The position of the graphic. You can access or change
-        using position.x, position.y, etc."""
+        """position of the graphic, [x, y, z]"""
         return self.world_object.world.position
 
     @property
     def position_x(self) -> float:
+        """x-axis position of the graphic"""
         return self.world_object.world.x
 
     @property
     def position_y(self) -> float:
+        """y-axis position of the graphic"""
         return self.world_object.world.y
 
     @property
     def position_z(self) -> float:
+        """z-axis position of the graphic"""
         return self.world_object.world.z
 
     @position.setter
@@ -390,7 +393,19 @@ def graphics(self) -> np.ndarray[Graphic]:
         return self._graphics_array
 
     def add_graphic(self, graphic: Graphic, reset_index: False):
-        """Add a graphic to the collection"""
+        """
+        Add a graphic to the collection.
+
+        Parameters
+        ----------
+        graphic: Graphic
+            graphic to add, must be a real ``Graphic`` not a proxy
+
+        reset_index: bool, default ``False``
+            reset the collection index
+
+        """
+
         if not type(graphic).__name__ == self.child_type:
             raise TypeError(
                 f"Can only add graphics of the same type to a collection, "
@@ -413,7 +428,19 @@ def add_graphic(self, graphic: Graphic, reset_index: False):
         self._graphics_changed = True
 
     def remove_graphic(self, graphic: Graphic, reset_index: True):
-        """Remove a graphic from the collection"""
+        """
+        Remove a graphic from the collection.
+
+        Parameters
+        ----------
+        graphic: Graphic
+            graphic to remove
+
+        reset_index: bool, default ``False``
+            reset the collection index
+
+        """
+
         self._graphics.remove(graphic.loc)
 
         if reset_index:
@@ -486,8 +513,8 @@ def __init__(
                 setattr(self, attr_name, collection_feature)
 
     @property
-    def graphics(self) -> Tuple[Graphic]:
-        """Returns a tuple of the selected graphics."""
+    def graphics(self) -> np.ndarray[Graphic]:
+        """Returns an array of the selected graphics. Always returns a proxy to the Graphic"""
         return tuple(self._selection)
 
     def __setattr__(self, key, value):

diff --git a/fastplotlib/graphics/_features/_base.py b/fastplotlib/graphics/_features/_base.py
@@ -49,7 +49,7 @@ class FeatureEvent:
     ----------
     type: str, example "colors"
 
-    pick_info: dict in the form:
+    pick_info: dict:
 
         ============== =============================================================================
         key             value
@@ -59,6 +59,9 @@ class FeatureEvent:
         "new_data:      the new data for this feature
         ============== =============================================================================
 
+        .. note::
+            pick info varies between features, this is just the general structure
+
     """
 
     def __init__(self, type: str, pick_info: dict):
@@ -97,8 +100,17 @@ def __init__(self, parent, data: Any, collection_index: int = None):
     def __call__(self, *args, **kwargs):
         return self._data
 
-    def block_events(self, b: bool):
-        self._block_events = b
+    def block_events(self, val: bool):
+        """
+        Block all events from this feature
+
+        Parameters
+        ----------
+        val: bool
+            ``True`` or ``False``
+
+        """
+        self._block_events = val
 
     @abstractmethod
     def _set(self, value):
@@ -113,9 +125,10 @@ def _parse_set_value(self, value):
     def add_event_handler(self, handler: callable):
         """
         Add an event handler. All added event handlers are called when this feature changes.
-        The `handler` can optionally accept ``FeatureEvent`` as the first and only argument.
+        The ``handler`` can optionally accept a :class:`.FeatureEvent` as the first and only argument.
         The ``FeatureEvent`` only has two attributes, ``type`` which denotes the type of event
-        as a ``str`` in the form of "<feature_name>", such as "color".
+        as a ``str`` in the form of "<feature_name>", such as "color". And ``pick_info`` which contains
+        information about the event and Graphic that triggered it.
 
         Parameters
         ----------
@@ -134,7 +147,7 @@ def add_event_handler(self, handler: callable):
 
     def remove_event_handler(self, handler: callable):
         """
-        Remove a registered event handler
+        Remove a registered event ``handler``.
 
         Parameters
         ----------
@@ -148,6 +161,7 @@ def remove_event_handler(self, handler: callable):
         self._event_handlers.remove(handler)
 
     def clear_event_handlers(self):
+        """Clear all event handlers"""
         self._event_handlers.clear()
 
     # TODO: maybe this can be implemented right here in the base class

diff --git a/fastplotlib/graphics/_features/_selection_features.py b/fastplotlib/graphics/_features/_selection_features.py
@@ -127,7 +127,6 @@
 )
 
 
-
 class LinearSelectionFeature(GraphicFeature):
     # A bit much to have a class for this but this allows it to integrate with the fastplotlib callback system
     """

diff --git a/fastplotlib/graphics/image.py b/fastplotlib/graphics/image.py
@@ -19,12 +19,12 @@
 )
 
 
-class _ImageHeatmapSelectorsMixin:
+class _AddSelectorsMixin:
     def add_linear_selector(
         self, selection: int = None, padding: float = None, **kwargs
     ) -> LinearSelector:
         """
-        Adds a linear selector.
+        Adds a :class:`.LinearSelector`.
 
         Parameters
         ----------
@@ -83,8 +83,7 @@ def add_linear_region_selector(
         self, padding: float = None, **kwargs
     ) -> LinearRegionSelector:
         """
-        Add a :class:`.LinearRegionSelector`. Selectors are just ``Graphic`` objects, so you can manage,
-        remove, or delete them from a plot area just like any other ``Graphic``.
+        Add a :class:`.LinearRegionSelector`.
 
         Parameters
         ----------
@@ -196,7 +195,7 @@ def _add_plot_area_hook(self, plot_area):
         self._plot_area = plot_area
 
 
-class ImageGraphic(Graphic, Interaction, _ImageHeatmapSelectorsMixin):
+class ImageGraphic(Graphic, Interaction, _AddSelectorsMixin):
     feature_events = ("data", "cmap", "present")
 
     def __init__(
@@ -359,7 +358,7 @@ def col_chunk_index(self, index: int):
         self._col_chunk_index = index
 
 
-class HeatmapGraphic(Graphic, Interaction, _ImageHeatmapSelectorsMixin):
+class HeatmapGraphic(Graphic, Interaction, _AddSelectorsMixin):
     feature_events = (
         "data",
         "cmap",

diff --git a/fastplotlib/graphics/line.py b/fastplotlib/graphics/line.py
@@ -66,11 +66,15 @@ def __init__(
 
         **data**: :class:`.ImageDataFeature`
             Manages the line [x, y, z] positions data buffer, allows regular and fancy indexing.
-            ex: ``scatter.data[:, 0] = 5```, ``scatter.data[xs > 5] = 3``
 
         **colors**: :class:`.ColorFeature`
             Manages the color buffer, allows regular and fancy indexing.
-            ex: ``scatter.data[:, 1] = 0.5``, ``scatter.colors[xs > 5] = "cyan"``
+
+        **cmap**: :class:`.CmapFeature`
+            Manages the cmap, wraps :class:`.ColorFeature` to add additional functionality relevant to cmaps.
+
+        **thickness**: :class:`.ThicknessFeature`
+            Manages the thickness feature of the lines.
 
         **present**: :class:`.PresentFeature`
             Control the presence of the Graphic in the scene, set to ``True`` or ``False``
-Original file line number
+Diff line change
@@ Expand Up / @@ -127,7 +127,6 @@ @@
     )
     class LinearSelectionFeature(GraphicFeature):
         # A bit much to have a class for this but this allows it to integrate with the fastplotlib callback system
         """
@@ Expand Down @@