Enhance documentation for figure, markers, and widget classes with detailed parameter descriptions, examples, and return values

Author: CSSFrancis

anyplotlib/figure.py

@@ -37,11 +37,44 @@
 class Figure(anywidget.AnyWidget):
     """Multi-panel interactive figure widget.
 
-    Create via :func:`subplots` or directly::
+    The top-level container for all plots and the only ``anywidget.AnyWidget``
+    subclass in anyplotlib. It owns all traitlets and acts as the Python ↔
+    JavaScript bridge via the ``figure_esm.js`` canvas renderer.
+
+    Create via :func:`subplots` (recommended) or directly::
 
         fig = Figure(2, 2, figsize=(800, 600))
         ax  = fig.add_subplot((0, 0))
         v2d = ax.imshow(data)
+
+    Parameters
+    ----------
+    nrows, ncols : int, optional
+        Grid dimensions. Default 1 row, 1 column.
+    figsize : (width, height), optional
+        Figure size in CSS pixels. Default ``(640, 480)``.
+    width_ratios : list of float, optional
+        Relative column widths. Length must equal *ncols*.
+    height_ratios : list of float, optional
+        Relative row heights. Length must equal *nrows*.
+    sharex, sharey : bool, optional
+        Link pan/zoom across all panels on the respective axis.
+        Default False (independent pan/zoom per panel).
+
+    Attributes
+    ----------
+    fig_width : int
+        Current figure width in pixels (synced with JS).
+    fig_height : int
+        Current figure height in pixels (synced with JS).
+    layout_json : str
+        JSON serialization of the grid layout (synced with JS).
+    event_json : str
+        JSON serialization of interaction events from JS.
+
+    See Also
+    --------
+    subplots : Recommended factory for creating Figure and Axes grid.
     """
 
     layout_json = traitlets.Unicode("{}").tag(sync=True)
@@ -75,11 +108,29 @@ def add_subplot(self, spec) -> Axes:
 
         Parameters
         ----------
-        spec : SubplotSpec | int | (row, col) tuple
+        spec : SubplotSpec or int or (row, col) tuple
+            Specifies which grid cell(s) to occupy:
             - ``SubplotSpec``: used directly (e.g. from ``GridSpec[r, c]``).
             - ``int``: converted to ``(row, col)`` via ``divmod(spec, ncols)``,
               matching ``matplotlib.Figure.add_subplot(num)`` numbering.
             - ``(row, col)`` tuple: selects a single cell.
+
+        Returns
+        -------
+        Axes
+            The subplot axes object. Call plotting methods like ``.imshow()``,
+            ``.plot()``, ``.bar()`` to attach data.
+
+        Raises
+        ------
+        TypeError
+            If *spec* is not a SubplotSpec, int, or tuple.
+
+        Examples
+        --------
+        >>> fig = Figure(2, 2)
+        >>> ax1 = fig.add_subplot(0)       # top-left (via numbering)
+        >>> ax2 = fig.add_subplot((0, 1))  # top-right (via tuple)
         """
         if isinstance(spec, SubplotSpec):
             pass  # use as-is
@@ -229,6 +280,14 @@ def _push_widget(self, panel_id: str, widget_id: str, fields: dict) -> None:
 
     # ── helpers ───────────────────────────────────────────────────────────────
     def get_axes(self) -> list:
+        """Return a list of all Axes, sorted by grid position.
+
+        Returns
+        -------
+        list of Axes
+            Axes sorted by (row_start, col_start) to match typical left-to-right,
+            top-to-bottom iteration order.
+        """
         return sorted(self._axes_map.values(),
                       key=lambda a: (a._spec.row_start, a._spec.col_start))
 
@@ -238,6 +297,11 @@ def _repr_html_(self) -> str:
         Used by Sphinx Gallery (via :class:`~docs._sg_html_scraper.ViewerScraper`)
         and by any HTML-capable notebook frontend that falls back to
         ``_repr_html_`` instead of the full ipywidgets protocol.
+
+        Returns
+        -------
+        str
+            HTML string containing an embedded iframe with srcdoc attribute.
         """
         from anyplotlib._repr_utils import repr_html_iframe
         return repr_html_iframe(self)

anyplotlib/markers.py

@@ -99,14 +99,22 @@ def __init__(self, marker_type: str, name: str, kwargs: dict, push_fn):
 
     # ------------------------------------------------------------------
     def set(self, **kwargs) -> None:
-        """Update one or more properties and push the change to the plot."""
+        """Update one or more properties and push the change to the plot.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Properties to update (e.g., offsets, radius, facecolors).
+            Matplotlib-style names are translated to wire format.
+        """
         self._data.update(kwargs)
         self._push_fn()
 
     def __repr__(self) -> str:  # pragma: no cover
         return f"MarkerGroup(type={self._type!r}, name={self._name!r}, n={self._count()})"
 
     def _count(self) -> int:
+        """Return the number of markers in this group."""
         offs = self._data.get("offsets")
         if offs is None:
             return 0
@@ -119,7 +127,19 @@ def _count(self) -> int:
     # Wire-format serialisation
     # ------------------------------------------------------------------
     def to_wire(self, group_id: str) -> dict:
-        """Return a dict in the JS wire format for this marker group."""
+        """Return a dict in the JS wire format for this marker group.
+
+        Parameters
+        ----------
+        group_id : str
+            Unique identifier for this marker group (usually UUID).
+
+        Returns
+        -------
+        dict
+            Wire-format dict with type-specific structure, ready for JSON
+            serialization and transmission to the JavaScript renderer.
+        """
         d = self._data
         t = self._type
 
@@ -333,6 +353,13 @@ class MarkerTypeDict:
 
     Any modification (``__setitem__``, ``__delitem__``) automatically triggers
     the ``_push_fn`` callback so the plot re-renders.
+
+    Parameters
+    ----------
+    marker_type : str
+        Type of markers (e.g., 'circles', 'arrows', 'lines').
+    push_fn : callable
+        Zero-arg callback to trigger re-render on mutations.
     """
 
     def __init__(self, marker_type: str, push_fn):
@@ -343,38 +370,112 @@ def __init__(self, marker_type: str, push_fn):
     # ------------------------------------------------------------------
     # dict-like interface
     def __getitem__(self, name: str) -> MarkerGroup:
+        """Return a MarkerGroup by name.
+
+        Parameters
+        ----------
+        name : str
+            Name of the marker group.
+
+        Returns
+        -------
+        MarkerGroup
+            The requested marker group.
+
+        Raises
+        ------
+        KeyError
+            If the name is not found.
+        """
         return self._groups[name]
 
     def __setitem__(self, name: str, group: MarkerGroup) -> None:
+        """Register a MarkerGroup and trigger re-render.
+
+        Parameters
+        ----------
+        name : str
+            Name to register the group under.
+        group : MarkerGroup
+            The marker group object.
+        """
         self._groups[name] = group
         self._push_fn()
 
     def __delitem__(self, name: str) -> None:
+        """Remove a MarkerGroup by name and trigger re-render.
+
+        Parameters
+        ----------
+        name : str
+            Name of the group to remove.
+
+        Raises
+        ------
+        KeyError
+            If the name is not found.
+        """
         del self._groups[name]
         self._push_fn()
 
     def __contains__(self, name: object) -> bool:
+        """Check if a named group exists.
+
+        Parameters
+        ----------
+        name : object
+            Name to check.
+
+        Returns
+        -------
+        bool
+            True if the group exists.
+        """
         return name in self._groups
 
     def __iter__(self):
+        """Iterate over group names."""
         return iter(self._groups)
 
     def __len__(self) -> int:
+        """Return the number of groups."""
         return len(self._groups)
 
     def __repr__(self) -> str:  # pragma: no cover
         return f"MarkerTypeDict(type={self._type!r}, groups={list(self._groups)})"
 
     def keys(self):
+        """Return group names."""
         return self._groups.keys()
 
     def values(self):
+        """Return MarkerGroup objects."""
         return self._groups.values()
 
     def items(self):
+        """Return (name, MarkerGroup) pairs."""
         return self._groups.items()
 
     def pop(self, name: str, *args):
+        """Remove and return a MarkerGroup by name.
+
+        Parameters
+        ----------
+        name : str
+            Name of the group to remove.
+        *args : optional
+            Default value if name is not found.
+
+        Returns
+        -------
+        MarkerGroup
+            The removed group, or default value if provided.
+
+        Raises
+        ------
+        KeyError
+            If name is not found and no default is provided.
+        """
         result = self._groups.pop(name, *args)
         self._push_fn()
         return result
@@ -437,6 +538,23 @@ def __init__(self, push_fn, allowed: frozenset | None = None):
 
     # ------------------------------------------------------------------
     def __getitem__(self, marker_type: str) -> MarkerTypeDict:
+        """Return the MarkerTypeDict for a type, auto-creating if needed.
+
+        Parameters
+        ----------
+        marker_type : str
+            Type name (e.g., 'circles', 'lines', 'arrows').
+
+        Returns
+        -------
+        MarkerTypeDict
+            The dict of named groups for this type.
+
+        Raises
+        ------
+        ValueError
+            If the type is not in the allowed set (if one was provided).
+        """
         if self._allowed is not None and marker_type not in self._allowed:
             raise ValueError(
                 f"Marker type '{marker_type}' is not allowed on this panel. "
@@ -447,9 +565,11 @@ def __getitem__(self, marker_type: str) -> MarkerTypeDict:
         return self._types[marker_type]
 
     def __contains__(self, marker_type: object) -> bool:
+        """Check if a marker type has any registered groups."""
         return marker_type in self._types
 
     def __iter__(self):
+        """Iterate over marker types that have registered groups."""
         return iter(self._types)
 
     def __repr__(self) -> str:  # pragma: no cover
@@ -482,16 +602,23 @@ def add(self, marker_type: str, name: str | None = None, **kwargs) -> MarkerGrou
 
         Parameters
         ----------
-        marker_type :
-            Type string, e.g. ``'circles'``.
-        name :
-            Group name.  Auto-generated (``'circles_1'`` etc.) if ``None``.
-        **kwargs :
-            Matplotlib-style kwargs for the group.
+        marker_type : str
+            Type string, e.g. ``'circles'``, ``'lines'``, ``'arrows'``.
+        name : str, optional
+            Group name. Auto-generated (``'circles_1'`` etc.) if ``None``.
+        **kwargs : dict
+            Matplotlib-style kwargs for the group (offsets, radius, colors, etc.).
 
         Returns
         -------
         MarkerGroup
+            The created marker group. Call ``.set()`` to update, or access
+            properties as attributes.
+
+        Examples
+        --------
+        >>> group = registry.add("circles", name="my_circles", offsets=[[10, 20]], radius=5)
+        >>> group.set(radius=8)
         """
         if name is None:
             name = self._auto_name(marker_type)
@@ -501,16 +628,35 @@ def add(self, marker_type: str, name: str | None = None, **kwargs) -> MarkerGrou
         return g
 
     def remove(self, marker_type: str, name: str) -> None:
-        """Remove a named group (triggers a push)."""
+        """Remove a named marker group and trigger re-render.
+
+        Parameters
+        ----------
+        marker_type : str
+            Type of the group.
+        name : str
+            Name of the group to remove.
+
+        Raises
+        ------
+        KeyError
+            If the type or name is not found.
+        """
         del self[marker_type][name]     # MarkerTypeDict.__delitem__ pushes
 
     def clear(self) -> None:
-        """Remove all markers of all types."""
+        """Remove all markers of all types and trigger re-render."""
         self._types.clear()
         self._push_fn()
 
     def to_wire_list(self) -> list:
-        """Flatten the full registry to a list of wire-format dicts."""
+        """Flatten the full registry to a list of wire-format dicts.
+
+        Returns
+        -------
+        list of dict
+            Wire-format dicts ready for JSON serialization and JS rendering.
+        """
         out = []
         for td in self._types.values():
             out.extend(td.to_wire_list())