Add detailed docstrings and examples for callbacks and figure modules; create new RST files for callbacks, figure plots, markers, and widgets

Author: CSSFrancis

README.md

@@ -10,8 +10,7 @@ although the scope is intentionally limited in the following ways:
 no `plt.imshow` or `plt.plot` – instead, you create a Figure object and call methods on it to add data
 and customize the plot. This is a deliberate choice to avoid the pitfalls of the stateful API.
 
-python
-```
+```python
 import anyplotlib as apl
 import matplotlib.pyplot as plt
 
@@ -43,10 +42,11 @@ environment that supports `AnyWidget`, including Jupyter notebooks, JupyterLab,
 the hood, `AnyWidget` uses a pure-JavaScript implementation of the widget protocol, which allows for fast rendering
 and interactivity.
 
-**Disclaimer**: This project is in the early stages of development.  Additionally many of the
-javascript code was optimized using LLM's. That being said, the javascript/python code is fairly minimal,
-and not too difficult to understand.
+## Getting Started
 
+Install from PyPI:
+```bash
+pip install anyplotlib
+```
 
-**Disclaimer #2**: Mostly this project is to see __if__ something like this is possible, it remains to be
-seen if this can be developed into a full-fledged plotting library.  The hope is that this can be.
+See the [documentation](https://cssfrancis.github.io/anyplotlib/) for more information.

anyplotlib/callbacks.py

@@ -1,3 +1,32 @@
+"""
+callbacks.py
+============
+
+Lightweight two-class event system used by every plot object and widget.
+
+:class:`CallbackRegistry`
+    Per-object store of named callbacks.  Every plot object and widget
+    exposes ``on_changed``, ``on_release``, ``on_click``, and ``on_key``
+    decorator methods that connect handlers through this registry.
+
+:class:`Event`
+    Immutable data-carrier passed to every callback.  All keys in the
+    raw JS payload are accessible as attributes (``event.zoom``,
+    ``event.cx``, etc.) in addition to the typed ``event_type``,
+    ``source``, and ``data`` fields.
+
+Example
+-------
+.. code-block:: python
+
+    fig, ax = apl.subplots(1, 1)
+    plot = ax.imshow(data)
+
+    @plot.on_release
+    def on_settle(event):
+        print(f"zoom={event.zoom:.2f}  center=({event.center_x:.3f}, {event.center_y:.3f})")
+"""
+
 from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any, Callable

anyplotlib/figure.py

@@ -1,3 +1,27 @@
+"""
+figure.py
+=========
+
+Top-level :class:`Figure` widget and the :func:`subplots` factory.
+
+``Figure`` is the only ``anywidget.AnyWidget`` subclass in anyplotlib.
+It owns all traitlets and acts as the Python ↔ JavaScript bridge.
+Use :func:`subplots` (the recommended entry-point) or construct a
+``Figure`` directly and call :meth:`Figure.add_subplot` to attach data.
+
+Example
+-------
+.. code-block:: python
+
+    import numpy as np
+    import anyplotlib as apl
+
+    fig, axs = apl.subplots(1, 2, figsize=(800, 400))
+    axs[0].imshow(np.random.standard_normal((128, 128)))
+    axs[1].plot(np.sin(np.linspace(0, 6.28, 256)))
+    fig
+"""
+
 from __future__ import annotations
 import json, pathlib
 import anywidget, numpy as np, traitlets

docs/api/callbacks.rst

@@ -0,0 +1,9 @@
+Callbacks
+=========
+
+.. automodule:: anyplotlib.callbacks
+   :members:
+   :undoc-members: False
+   :show-inheritance:
+   :member-order: bysource
+

docs/api/figure_plots.rst

@@ -0,0 +1,9 @@
+Figure Plots
+============
+
+.. automodule:: anyplotlib.figure_plots
+   :members:
+   :undoc-members: False
+   :show-inheritance:
+   :member-order: bysource
+

docs/api/index.rst

@@ -2,7 +2,10 @@ API Reference
 =============
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    figure
-
+   figure_plots
+   markers
+   widgets
+   callbacks

docs/api/markers.rst

@@ -0,0 +1,9 @@
+Markers
+=======
+
+.. automodule:: anyplotlib.markers
+   :members:
+   :undoc-members: False
+   :show-inheritance:
+   :member-order: bysource
+

docs/api/widgets.rst

@@ -0,0 +1,9 @@
+Widgets
+=======
+
+.. automodule:: anyplotlib.widgets
+   :members:
+   :undoc-members: False
+   :show-inheritance:
+   :member-order: bysource
+

docs/conf.py

@@ -86,14 +86,10 @@
     "logo": {
         "image_light": "_static/anyplotlib.svg",
         "image_dark": "_static/anyplotlib.svg",
-        "text": "anyplotlib",
+        "text": "anyplotlib"
     },
-    "switcher": {
-        "json_url": f"{_base}switcher.json",
-        "version_match": _docs_version,
-    },
-    "navbar_end": ["version-switcher", "navbar-icon-links"],
-    "show_toc_level": 2,
+    "navbar_end": ["navbar-icon-links"],
+    "show_toc_level": 2
 }
 
 # -- autodoc options ---------------------------------------------------------

docs/getting_started.rst

@@ -4,11 +4,15 @@ Getting Started
 Installation
 ------------
 
-Clone the repository and install with ``uv`` (or pip)::
+Install via pip from PyPI (recommended)::
 
-    git clone https://github.com/your-org/anyplotlib.git
+    pip install anyplotlib
+
+Or clone the repository and install from source::
+
+    git clone https://github.com/CSSFrancis/anyplotlib.git
     cd anyplotlib
-    uv sync          # installs the project + all dependencies
+    uv sync          # or `pip install -e .`
 
 Quick start
 -----------