Merge pull request #30 from ZLLentz/cache-state

ENH: QOL improvements from the flight back

docs/source/daq_basic.rst

@@ -39,7 +39,7 @@ First, I will set up the `Daq` class in simulated mode. In practice, the
     from pcdsdaq.sim import set_sim_mode
 
     set_sim_mode(True)
-    daq = Daq(platform=4)  # Defined per hutch
+    daq = Daq()
 
 
 .. ipython:: python
@@ -50,13 +50,15 @@ First, I will set up the `Daq` class in simulated mode. In practice, the
     from pcdsdaq.sim import set_sim_mode
 
     set_sim_mode(True)
-    daq = Daq(platform=4)  # Defined per hutch
+    daq = Daq()
 
 
 Running Until Stop
 ------------------
 Calling `Daq.begin` with no arguments in the default configuration will
 run the daq indefinitely, until we manually stop it.
+You can also use `Daq.begin_infinite` to run the daq indefinitely with
+any configuration.
 Here I check `Daq.state` to verify that we've started running the daq.
 
 .. ipython:: python
@@ -108,6 +110,19 @@ We can pass ``wait=True`` to skip the `Daq.wait` call.
     daq.state
 
 
+Ending a Run
+------------
+As seen in the previous examples, `Daq.end_run` can be used to tell the daq
+that the current run is over. You can also do with with an argument to
+`Daq.begin` for a nice one-liner:
+
+.. ipython:: python
+
+    daq.state
+    daq.begin(duration=1, wait=True, end_run=True)
+    daq.state
+
+
 Recording Data
 --------------
 You can set `Daq.record` to ``True`` to record data. This is fairly simple:

docs/source/daq_config.rst

@@ -3,16 +3,10 @@ Configuration
 Some manual configuration is necessary to record data or to run
 special ``bluesky`` plans with daq support.
 
-In general, there are two kinds of `Daq.configure` arguments:
-those that are shared with `Daq.begin`, and those that are not.
-
-Arguments that are shared between the two methods act as defaults.
-For example, calling ``daq.configure(duration=3)`` will set the
-no-arguments behavior of ``daq.begin()`` to run the daq for 3 seconds.
-
 You can get the current configuration from `Daq.config`.
 Shown here is the default config:
 
+
 .. ipython:: python
     :suppress:
 
@@ -27,6 +21,22 @@ Shown here is the default config:
 
     daq.config
 
+You can also print this information nicely using `Daq.config_info`.
+
+You can configure the daq through `Daq.configure`, which configures
+the daq right away, or `Daq.preconfig`, which schedules a configuration
+to be done when it is next needed. This distinction is sometimes important
+because we cannot do a full configure during an open run, for example.
+As an aside, `Daq.configure` has a long return value, which may make
+`Daq.preconfig` the preferred method for interactive sessions.
+
+In general, there are two kinds of configuration arguments:
+those that are shared with `Daq.begin`, and those that are not.
+
+Arguments that are shared between the two methods act as defaults.
+For example, calling ``daq.configure(duration=3)`` will set the
+no-arguments behavior of ``daq.begin()`` to run the daq for 3 seconds.
+
 
 .. automethod:: pcdsdaq.daq.Daq.configure
    :noindex:

docs/source/plans_basic.rst

@@ -122,3 +122,11 @@ and back to the ``start`` positions, and then end the run.
 If you ignore the `daq_during_decorator`, this is just a normal ``plan``.
 This makes it simple to add the daq collecting data in the background
 to a normal ``bluesky`` ``plan``.
+
+
+After the Plan
+--------------
+The daq will automatically be returned to whatever state it was in before
+running the ``bluesky`` ``plan``. This means if you start from a disconnected
+state, we will disconnect, if you start from a running state we will return
+to running, and if you start from a configured state we'll stay connected.

docs/source/releases.rst

@@ -1,8 +1,8 @@
 Release History
 ###############
 
-Next Release
-============
+v2.0.0 (2018-05-27)
+===================
 
 Features
 --------
@@ -15,6 +15,12 @@ Features
   A calibcycle will be run when the `Daq` is triggered, and triggering will be
   reported as done when the `Daq` has stopped. This means it is viable to use
   the `Daq` inside normal plans like ``scan`` and ``count``.
+- Add an argument to `Daq.begin`: ``end_run=True`` will end the run once the
+  daq stops running, rather than leaving the run open.
+- Add `Daq.begin_infinite`
+- Add `Daq.config_info`
+- Restore daq state after a ``bluesky`` ``plan``, e.g. disconnect if we were
+  disconnected, run if we were running, etc.
 - Add support for scan PVs via the `ScanVars` class. This class attaches
   itself to a ``RunEngine`` and knows when to update each PV, provided that
   the ``plan`` has reasonable metadata.