Intents docs

docs/source/index.rst

@@ -47,6 +47,7 @@ Developer Documentation
    gui-plugin
    entry-points
    operation-plugin
+   intents
    workflow
    resources
 

docs/source/intents.md

@@ -0,0 +1,40 @@
+# Intents Documentation
+
+This documentation provides information on the use of Intents to annotate data, including how they're applied to `OperationPlugin`'s.
+
+*If you are new to developing Xi-CAM operations,
+it is recommended that you follow the [operations development guide](operation-plugin.md) first.*
+
+For more general development resources, see the [Resources](resources.md) page.
+
+## What Is an Intent?
+
+In Xi-CAM, an `Intent` generally represents a descriptive annotation of how to visualize data.
+Basically, an `Intent` is a recipe for constructing a visualization.
+When an `Intent` is associated with an operation, Xi-CAM may use it to automatically generate plots as you adjust your workflow.
+An `Intent` can be embedded in a Databroker `BluesklyRun`, so they may be preserved along with derived (and also raw) data.
+
+### The Lifecycle of an Intent
+
+A `GUIPlugin` that supports intents will contain a `CanvasManager`.
+Active intents will be rendered into a `Canvas` owned by the `CanvasManager`.
+When an `Intent` is activated, the manager may generate a new `Canvas` for its rendering.
+In cases such as co-plotting, a pre-existing `Canvas` may be used; that choice is based on the corresponding intents' `match_key` attributes.
+
+## What Types of Intents are Available?
+
+The list of intents is extensible via the `IntentPlugin`, however many use cases will fit into one of these generic types:
+
+- PlotIntent
+- ImageIntent
+- ErrorBarIntent
+- BarIntent
+
+Although these types are primitive, additional specialized features can be added to them by specifying `mixin`'s.
+
+## Adding Intents to Operations
+
+The `@intent(...)` decorator can be used to annotate an `OperationPlugin` as shown:
+```eval_rst
+.. autodecorator:: xicam.plugins.operationplugin.intent
+```

xicam/plugins/operationplugin.py

@@ -673,12 +673,12 @@ def intent(intent_type: Type[Intent], name="", output_map={}, *args, **kwargs):
     --------
     Make an operation that defines a PlotIntent that displays its plot item with a red line (pen='r' kwarg).
 
-    >>>@operation
-    >>>@output_names('output1', 'output2')
-    >>>@intent(PlotHint, name="Output1 v. Output2", output_map={'x': 'output1', 'y': 'output2'}, labels={} pen='r')
-    >>>def op():
-    >>>    ...
-    >>>    return(array_1, array_2)
+    >>> @operation
+    >>> @output_names('output1', 'output2')
+    >>> @intent(PlotHint, name="Output1 v. Output2", output_map={'x': 'output1', 'y': 'output2'}, labels={} pen='r')
+    >>> def op():
+    >>>     ...
+    >>>     return(array_1, array_2)
     """
     def decorator(func):
         if not hasattr(func, 'intent_blueprints'):