diff --git a/docs/Makefile b/docs/Makefile index 5117fbf5..7bb83626 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,6 +12,11 @@ BUILDDIR = _build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +clean: + @echo Removing files created by sphinx-build + rm -rf $(BUILDDIR) + rm -rf $(SOURCEDIR)/api/ + .PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new diff --git a/docs/guide/index.rst b/docs/guide/index.rst new file mode 100644 index 00000000..1dea6cd2 --- /dev/null +++ b/docs/guide/index.rst @@ -0,0 +1,7 @@ +Guide +===== + +.. toctree:: + :maxdepth: 1 + + third_party diff --git a/docs/guide/third_party.rst b/docs/guide/third_party.rst new file mode 100644 index 00000000..4a793e6c --- /dev/null +++ b/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 `QWidget <https://doc.qt.io/qtforpython-5/PySide2/QtWidgets/QWidget.html>`_. + +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. diff --git a/docs/index.rst b/docs/index.rst index abcb8e66..5b747e04 100644 --- a/docs/index.rst +++ b/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 diff --git a/src/napari_matplotlib/base.py b/src/napari_matplotlib/base.py index 4232cf71..daf7bac9 100644 --- a/src/napari_matplotlib/base.py +++ b/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__(