From d089160cd9dd6a6363c8da4a32dc65cf8b4fc45e Mon Sep 17 00:00:00 2001
From: ronpandolfi <ronpandolfi@gmail.com>
Date: Thu, 21 Jan 2021 11:31:44 -0800
Subject: [PATCH 1/3] Add intents docs

---
 docs/source/index.rst  |  1 +
 docs/source/intents.md | 47 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)
 create mode 100644 docs/source/intents.md

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 32c3d19d..44ccf92a 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -47,6 +47,7 @@ Developer Documentation
    gui-plugin
    entry-points
    operation-plugin
+   intents
    workflow
    resources
 
diff --git a/docs/source/intents.md b/docs/source/intents.md
new file mode 100644
index 00000000..5ee20b56
--- /dev/null
+++ b/docs/source/intents.md
@@ -0,0 +1,47 @@
+# 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.
+
+<!--Note that the examples in this documentation can be run in a python interpreter outside of Xi-CAM-->
+<!--(for demonstration purposes).-->
+<!--Auxiliary support code to be able to do this is marked with a comment ```# Only need if not running xicam```.-->
+<!--When developing within Xi-CAM, you will **not** need the lines of code marked with that comment.-->
+
+## 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.
+
+TODO: image representing intents visually
+
+### 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
+```

From 3219637d614ea9990435f25ab0034633eb27e6ae Mon Sep 17 00:00:00 2001
From: ronpandolfi <ronpandolfi@gmail.com>
Date: Thu, 21 Jan 2021 11:37:13 -0800
Subject: [PATCH 2/3] Fix example markup indentation

---
 xicam/plugins/operationplugin.py | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/xicam/plugins/operationplugin.py b/xicam/plugins/operationplugin.py
index 18f50a6b..60d4a968 100644
--- a/xicam/plugins/operationplugin.py
+++ b/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'):

From 345e97a9a1e9bf1b72a6435086329d1ec3ddf418 Mon Sep 17 00:00:00 2001
From: ronpandolfi <ronpandolfi@gmail.com>
Date: Thu, 21 Jan 2021 12:18:29 -0800
Subject: [PATCH 3/3] Remove comments

---
 docs/source/intents.md | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/docs/source/intents.md b/docs/source/intents.md
index 5ee20b56..a087f108 100644
--- a/docs/source/intents.md
+++ b/docs/source/intents.md
@@ -7,11 +7,6 @@ it is recommended that you follow the [operations development guide](operation-p
 
 For more general development resources, see the [Resources](resources.md) page.
 
-<!--Note that the examples in this documentation can be run in a python interpreter outside of Xi-CAM-->
-<!--(for demonstration purposes).-->
-<!--Auxiliary support code to be able to do this is marked with a comment ```# Only need if not running xicam```.-->
-<!--When developing within Xi-CAM, you will **not** need the lines of code marked with that comment.-->
-
 ## What Is an Intent?
 
 In Xi-CAM, an `Intent` generally represents a descriptive annotation of how to visualize data.
@@ -19,8 +14,6 @@ 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.
 
-TODO: image representing intents visually
-
 ### The Lifecycle of an Intent
 
 A `GUIPlugin` that supports intents will contain a `CanvasManager`.