Updated area detector documentation, and added a how-to guide section…

… to docs.

docs/how_to_guides/adding_devices.rst

@@ -0,0 +1,86 @@
+Adding Devices in Haven
+=======================
+
+This guide encompasses two concepts:
+
+- adding a new instance of a device that already has Haven support
+- adding a new category of device that does not have Haven support
+
+Existing Haven Support
+----------------------
+
+If the device you are using already has a device class created for it,
+then using the device only requires a suitable entry in the iconfig
+file. By inspecting the environmental variable HAVEN_CONFIG_FILES we
+can see that in this case the configuration file is
+``~/bluesky/iconfig.toml``, though your beamline may be different.
+
+.. code-block:: bash
+
+    $ echo $HAVEN_CONFIG_FILES
+    /home/beams/S255IDCUSER/bluesky/iconfig.toml
+
+Next, add a new section for this device. The TOML section name should
+be the device category, often a lower-case version of the device
+class. Most devices also accept at least the parameter *name*, which
+will be used to retrieve the device later from the instrument
+registry.
+
+In most cases the key "prefix" should list the IOC prefix, including
+the trailing ":". For this example, we will add a simple motor.
+
+.. code-block:: toml
+
+   [[ motor ]]
+   prefix = "255idc:m1"
+   name = "bpm"
+   
+Once this section has been added to ``iconfig.toml``, then the device
+can be loaded from the instrument registry. No special configuration
+is generally necessary.
+
+This device will be loaded once the beamline's load method is called,
+though this **usually done automatically** during startup.
+
+.. code-block::
+
+    from haven.instrument import beamline
+    await beamline.load()
+    bpm_motor = beamline.registry['bpm']
+
+
+New Haven Support
+-----------------
+
+If Haven does not already have support for the device, this will need
+to be added. Details on how to create Ophyd and Ophyd-async devices is
+beyond the scope of this guide. Assume for this example that there is
+a file ``src/haven/devices/toaster.py`` which contains a device class
+``Toaster()`` that accepts the parameters *max_power*, *num_slots*,
+*prefix*, and *name*.
+
+To let the Haven instrument loader know about this device, edit the
+file ``src/haven/instrument.py`` and look for the line like ``beamline
+= Instrument({``. Following this line is a mapping of device classes
+to their TOML section names. We will now add our new device to this mapping:
+
+.. code-block:: python
+
+    beamline = Instrument({
+        ...
+	"toaster": Toaster,
+	...
+    })
+
+The order does not usually matter, though device classes will be
+created in the order they are retrieved from this dictionary.
+
+Now the following section can be added to the ``iconfig.toml`` file.
+
+.. code-block:: toml
+
+    [[ toaster ]]
+    name = "sunbeam"
+    prefix = "255idc:toast:"
+    num_slots = 2  # 2-slot toaster
+    max_power = 1200  # Watts

docs/how_to_guides/index.rst

@@ -0,0 +1,14 @@
+##############
+How-To Guides
+##############
+
+These guides provide a step-by-step guide for performing specific
+tasks. In contrast with tutorials, these guides assume a basic level
+of understanding of topics like Haven, Ophyd, Ophyd-async, and
+Bluesky.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   adding_devices.rst

docs/index.rst

@@ -16,6 +16,7 @@ Welcome to haven's documentation!
    :caption: Contents:
 
    tutorials/index.rst
+   how_to_guides/index.rst
    topic_guides/index.rst
    haven/haven.rst
 

docs/topic_guides/area_detectors.rst

@@ -3,14 +3,16 @@ Area Detectors and Cameras
 ###########################
 
 Area detectors are all largely the same but with small variations from
-device-to-device. All the device definitions for area detectors are in
-the :py:mod:`haven.devices.area_detector` module.
+device-to-device. Old (threaded) device definitions for area detectors
+are in the :py:mod:`haven.devices.area_detector` module. Newer
+(awaitable) device definitions are in the
+:pyd:mod:`haven.devices.detectors` package.
 
 Currently supported detectors:
 
 - Eiger 500K (:py:class:`~haven.devices.area_detector.Eiger500K`)
 - Lambda (:py:class:`~haven.devices.area_detector.Lambda250K`)
-- Simulated detector (:py:class:`~haven.devices.area_detector.SimDetector`)
+- Simulated detector (:py:class:`~haven.devices.detectors.sim_detector.SimDetector`)
 
 EPICS and Ophyd do not make a distinction between area detectors and
 cameras. After all, a camera is just an area detector for visible
@@ -21,57 +23,6 @@ substantive difference is that cameras have the ophyd label "cameras",
 whereas non-camera area detectors (e.g. Eiger 500K), have the ophyd
 label "area_detectors". They can be used interchangeably in plans.
 
-.. warning::
-
-   Currently, cameras are not properly implemented in Haven. This will
-   be fixed soon.
-
-Using Devices in Haven
-======================
-
-If the device you are using already has a device class created for it,
-then using the device only requires a suitable entry in the iconfig
-file (``~/bluesky/instrument/iconfig.toml``). The iconfig section name
-should begin with "area_detector", and end with the device name
-(e.g. "area_detector.eiger"). The device name will be used to retrieve
-the device later from the instrument registry.
-
-The key "prefix" should list the IOC prefix, minus the trailing
-":". The key "device_class" should point to a subclass of ophyd's
-:py:class:`~ophyd.areadetector.detectors.DetectorBase` class that is
-defined in :py:mod:`haven.devices.area_detector`.
-
-
-.. code-block:: toml
-
-   [area_detector.eiger]
-
-   prefix = "dp_eiger_xrd91"
-   device_class = "Eiger500K"
-   
-
-Once this section has been added to ``iconfig.toml``, then the device
-can be loaded from the instrument registry. No special configuration
-is generally necessary.
-
-.. code-block:: python
-
-   >>> import haven
-   >>> haven.load_instrument()
-   >>> det = haven.registry.find("eiger")
-   >>> plan = haven.xafs_scan(..., detectors=[det])
-
-Usually, no special configuration is needed for area detectors. By
-default it will save HDF5 and TIFF files for each frame. The filenames
-for these TIFF and HDF5 files will be stored automatically to the
-database. The outputs of the stats plugins will also be saved.
-
-.. warning::
-
-   It is up you to make sure the file path settings are correct for
-   the HDF5 and TIFF NDplugins. Also, ensure that the routing is
-   correct for the ROI and STATS NDplugins.
-
 .. warning::
 
    The first time you stage the device after the IOC has been