Add docs on using as a third-party plugin developer

docs/guide/index.rst

@@ -0,0 +1,7 @@
+Guide
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+   third_party

docs/guide/third_party.rst

@@ -0,0 +1,54 @@
+Third-party plugins
+===================
+This page explains how ``napari-matplotlib`` can be used within third party plugins.
+
+``napari-matplotlib`` provides a ready-to-go widget with a Matplotlib toolbar and figure to third party plugin developers
+This widget is customised to match the theme of the main napari window.
+
+The widget can be found at `napari_matplotlib.base.NapariMPLWidget`.
+This class inherits from `~PyQt6.QtWidgets.QWidget`.
+
+The recommended way to use `~napari_matplotlib.base.NapariMPLWidget` is inside a new widget, adding it to the layout.
+This means you can add additional elements to your plugin layout alongside the Matplotlib figure.
+Here's a short example:
+
+.. code-block:: python
+
+    from qtpy.QtWidgets import QWidget
+    from napari_matplotlib.base import NapariMPLWidget
+
+    class MyPlugin(QWidget):
+        def __init__(self, napari_viewer: napari.viewer.Viewer, parent=None):
+            super().__init__(parent=parent)
+
+            # Any custom setup for your custom widget
+            ...
+
+            # Set up the plot widget
+            plot_widget =  NapariMPLWidget(napari_viewer, parent=self)
+            self.layout().addWidget(plot_widget)
+
+The following properties and methods are useful for working with the figure and any axes within the widget:
+
+- `~.BaseNapariMPLWidget.figure` provides access to the figure
+- :meth:`~.BaseNapariMPLWidget.add_single_axes` adds a single axes to the figure, which can be accessed using the ``.axes`` attribute.
+- :meth:`~.BaseNapariMPLWidget.apply_napari_colorscheme` can be used to apply the napari colorscheme to any Axes you setup manually on the figure.
+
+Working with napari layers
+--------------------------
+When either the layer selection or z-step in the napari viewer is changed
+:meth:`~.NapariMPLWidget.clear` and :meth:`~.NapariMPLWidget.draw` are called
+in turn. By default these do nothing, and are designed to be overriden by
+plugins to automatically re-draw any figures within the widget. Plugins can
+also override :meth:`~.NapariMPLWidget.on_update_layers` to do something when
+the layer selection changes. This can be used to do something without clearing
+or re-drawing any plots.
+
+Validating layer numbers and types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+By default :meth:`~.NapariMPLWidget.draw` will be called when any number of any
+type of napari layers are selected. The `~.NapariMPLWidget.n_layers_input`
+and `~.NapariMPLWidget.input_layer_types` class variables can be overriden to
+specify the number of selected napari layers and valid layer
+types that are taken as input. If the number of selected layers and their
+types do not match up with these class variables, no re-draw is called.

docs/index.rst

@@ -12,8 +12,12 @@ map one or more Image layers on to a 1D histogram plot.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Contents:
 
-   auto_examples/index
-   changelog
+   guide/index
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference
+
    api
+   changelog

src/napari_matplotlib/base.py

@@ -29,6 +29,11 @@ class BaseNapariMPLWidget(QWidget):
     are customised to match the visual style of the main napari window.
     It is not responsible for creating any Axes, because different
     widgets may want to implement different subplot layouts.
+
+    See Also
+    --------
+    NapariMPLWidget : A child class that also contains helpful attributes and
+        methods for working with napari layers.
     """
 
     def __init__(
@@ -121,6 +126,11 @@ class NapariMPLWidget(BaseNapariMPLWidget):
         Main napari viewer.
     layers : `list`
         List of currently selected napari layers.
+
+    See Also
+    --------
+    BaseNapariMPLWidget : The parent class of this widget. Contains helpful methods
+        for creating and working with the Matplotlib figure and any axes.
     """
 
     def __init__(