simplify configuration of IO modules

As the communicator class needed for a module can be specified,
in the configuration we do not need to specifiy it explicitly.

A new configurator function IO() is introduced for this, defining
names and uri only.

- update also configuration reference and a tutorial example
- update get_class function to accept attributes of classes like
  'frappy_demo.lakshore.TemperatureSensor.ioClass' and import from
  modules other than frappy... like 'test.test_iocfg.Mod'.
- add ioClass to the example class for the temperature controller
  tutorial

Change-Id: I3115371d612f14024e43bc6d38b642e1d27b314d
Reviewed-on: https://forge.frm2.tum.de/review/c/secop/frappy/+/38071
Tested-by: Jenkins Automated Tests <pedersen+jenkins@frm2.tum.de>
Reviewed-by: Markus Zolliker <markus.zolliker@psi.ch>

doc/source/configuration.inc

@@ -3,10 +3,14 @@ Configuration File
 
 .. _node configuration:
 
-:Node(equipment_id, description, interface, \*\*kwds):
+:Node:
 
     Specify the SEC-node properties.
 
+    .. code::
+
+        Node(equipment_id, description, interface, **kwds):
+
     The arguments are SECoP node properties and additional internal node configurations
 
     :Parameters:
@@ -18,9 +22,14 @@ Configuration File
 
 .. _mod configuration:
 
-:Mod(name, cls, description, \*\*kwds):
+:Mod:
 
     Create a SECoP module.
+
+    .. code::
+
+        Mod(name, cls, description, **kwds)
+
     Keyworded argument matching a parameter name are used to configure
     the initial value of a parameter. For configuring the parameter properties
     the value must be an instance of **Param**, using the keyworded arguments
@@ -37,22 +46,60 @@ Configuration File
 
 .. _param configuration:
 
-:Param(value=<undef>, \*\*kwds):
+:Param:
 
     Configure a parameter
 
+    .. code::
+
+        Param(value=<undef>, **kwds):
+
     :Parameters:
 
         - **value** - if given, the initial value of the parameter
         - **kwds** - parameter or datatype SECoP properties (see :class:`frappy.param.Parameter`
           and :class:`frappy.datatypes.Datatypes`)
 
+.. _io configuration:
+
+:IO:
+
+    Configure IO modules (communicators)
+
+    .. code::
+
+        IO(<io name>, <uri>, ...)
+
+
+    It is recommended that the class of the needed IO is specified as class
+    attribute ioClass on the modules class. In this case, for the configuration
+    of the IO modules only their name and URI is needed, for example:
+
+    .. code::
+
+        IO('io_T', 'tcp://192.168.1.1:7777', export=False)
+        IO('io_C', 'serial:///dev/tty_USB0&baudrate=9600', export=False)
+
+        Mod('T_sample', 'frappy_psi.lakeshore.TemperatureSensor', 'the sample T',
+            io='io_T', channel='C')
+        Mod('T_main', 'frappy_psi.lakeshore.TemperatureLoop', 'the main T',
+            io='io_T', channel='A')
+        Mod('C_sample', 'frappy_psi.ah2700.Capacitance', 'the sample capacitance',
+            io='io_C')
+
+    The ``export=False`` argument tells Frappy to hide both communicators.
+
+
 .. _command configuration:
 
-:Command(\*\*kwds):
+:Command:
 
     Configure a command
 
+    .. code::
+
+        Command(**kwds)
+
     :Parameters:
 
         - **kwds** - command SECoP properties (see :class:`frappy.param.Commands`)

doc/source/reference.rst

@@ -140,4 +140,4 @@ Exception classes
 .. automodule:: frappy.errors
     :members:
 
-.. include:: configuration.rst
+.. include:: configuration.inc

doc/source/tutorial_t_control.rst

@@ -99,16 +99,11 @@ We choose the name *example_cryo* and create therefore a configuration file
     Node('example_cryo.psi.ch',  # a globally unique identification
          'this is an example cryostat for the Frappy tutorial',  # describes the node
           interface='tcp://10767')  # you might choose any port number > 1024
-    Mod('io',  # the name of the module
-        'frappy_psi.lakeshore.LakeshoreIO',  # the class used for communication
-        'communication to main controller',  # a description
-        # the serial connection, including serial settings (see frappy.io.IOBase):
-        uri='serial://COM6:?baudrate=57600+parity=odd+bytesize=7',
-       )
+    IO('io', 'serial://COM6:?baudrate=57600+parity=odd+bytesize=7')
     Mod('T',
         'frappy_psi.lakeshore.TemperatureSensor',
         'Sample Temperature',
-        io='io',  # refers to above defined module 'io'
+        io='io',  # refers to above defined io module called 'io'
         channel='A',  # the channel on the LakeShore for this module
         value=Param(max=470),  # alter the maximum expected T
        )
@@ -120,8 +115,8 @@ Usually the only important value in the server address is the TCP port under whi
 server will be accessible. Currently only the tcp scheme is supported.
 
 Then for each module a :ref:`Mod <mod configuration>` section follows.
-We have to create the ``io`` module for communication first, with
-the ``uri`` as its most important argument.
+But first we have to create the ``io`` module for communication.
+For this we use an :ref:`IO <io configuration>` section.
 In case of a serial connection the prefix is ``serial://``. On a Windows machine, the full
 uri is something like ``serial://COM6:?baudrate=9600`` on a linux system it might be
 ``serial:///dev/ttyUSB0?baudrate=9600``. In case of a LAN connection, the uri should