Docs update

concert/experiments/base.py

@@ -1,5 +1,5 @@
 """
-An experiment can be run multiple times. The base :py:class:`Experiment`
+An experiment can be run multiple times. The base :py:class:`.Experiment`
 takes care of proper logging structure.
 """
 
@@ -18,7 +18,7 @@
 class Acquisition(object):
 
     """
-    An acquisition object connects data producer to a consumer
+    An acquisition object connects data generator to consumers.
 
     .. py:attribute:: generator_caller
 
@@ -51,10 +51,10 @@ def __repr__(self):
 
 class Experiment(object):
 
-    """
+    r"""
     Experiment base class. An experiment can be run multiple times
     with logging output saved on disk. The log from every
-    :py:meth:`Experiment.run` is saved in the current experiment directory
+    :py:meth:`.base.Experiment.run` is saved in the current experiment directory
     given by *directory_prefix*.
 
     .. py:attribute:: acquisitions
@@ -67,7 +67,7 @@ class Experiment(object):
        at each experiment run a new directory given by the prefix and
        the current iteration is created. If the *directory_prefix* is a
        simple string then the individual experiment runs are stored in
-       its subdirectories starting with scan_ and suffixed by the run
+       its subdirectories starting with scan\_ and suffixed by the run
        iteration.
 
     .. py:attribute:: log
@@ -137,8 +137,10 @@ def acquire(self):
     @async
     def run(self):
         """
+        run()
+
         Create current directory, attach logging output to file and run the
-        :meth:`.Experiment.acquire`. After the run is complete the logging
+        :meth:`.base.Experiment.acquire`. After the run is complete the logging
         is cleaned up automatically. This method should *not* be overriden.
         """
         # Create directory for next scan

docs/user/topics/experiments.rst

@@ -2,14 +2,50 @@
 Experiments
 ===========
 
+Experiments connect data acquisition and processing. They can be run multiple times
+by the :meth:`.base.Experiment.run`, they take care of proper file structure and
+logging output.
+
+
+Acquisition
+-----------
+
+Experiments consist of :class:`.Acquisition` objects which encapsulate data generator
+and consumers for a particular experiment part (dark fields, radiographs, ...). This
+way the experiments can be broken up into smaller logical pieces. A single acquisition
+object needs to be reproducible in order to repeat an experiment more times, thus we
+specify its generator and consumers as callables which return the actual generator or
+consumer. We need to do this because generators cannot be "restarted". An example of
+an acquisition could look like this::
+
+    from concert.coroutines import coroutine
+    from concert.experiments import Acquisition
+
+    # This is a real generator, num_items is provided somewhere in our session
+    def produce():
+        for i in range(num_items):
+            yield i
+
+    # A simple data forwarder filter, next_consumer has to be already defined
+    @coroutine
+    def consumer():
+        while True:
+            item = yield
+            next_consumer.send(item)
+
+    acquisition = Acquisition('foo', produce, consumer_callers=[consumer])
+    # Now we can run the acquisition
+    acquisition()
+
+.. autoclass:: concert.experiments.base.Acquisition
+    :members:
+
 
-Experiments help to conduct real experiments more effectively without needing to worry
-about current directory path and creation, saving files and so on. Particular
-:class:`.Experiment` subclass defines how the experiment steps are conducted and brings
-together data acquisition and processing. The base class provides directory
-creation functionality and logging redirection into a file in the current
-experiment directory.
+Base
+----
 
+Base :class:`.base.Experiment` makes sure a directory for each run is created and
+logger output goes to that directory.
 
 .. autoclass:: concert.experiments.base.Experiment
     :members:
@@ -18,10 +54,9 @@ experiment directory.
 Imaging
 -------
 
-Imaging experiments all subclass :class:`.Radiography`. Every experiment
-consists of taking dark, flat fields and radiographs. If the particular
-methods are not provided or overriden, the image type is skipped.
+Imaging experiments all subclass :class:`.imaging.Experiment`, which makes sure
+all the acquired frames are written to disk.
 
 
-.. autoclass:: concert.experiments.imaging.Radiography
+.. autoclass:: concert.experiments.imaging.Experiment
     :members: