Merge pull request #4 from jenshnielsen/feature/device_meta_docs

Add Delegate module to the api docs

Author: Guen Prawiroatmodjo

docs/api/instrument/delegate.rst

@@ -0,0 +1,17 @@
+qcodes.instrument.delegate
+--------------------------
+
+.. automodule:: qcodes.instrument.delegate
+   :members:
+
+.. automodule:: qcodes.instrument.delegate.delegate_instrument
+   :members:
+
+.. automodule:: qcodes.instrument.delegate.delegate_channel_instrument
+   :members:
+
+.. automodule:: qcodes.instrument.delegate.grouped_parameter
+   :members:
+
+.. automodule:: qcodes.instrument.delegate.instrument_group
+   :members:

docs/api/instrument/index.rst

@@ -8,6 +8,7 @@ qcodes.instrument (Instruments)
     qcodes.instrument
     qcodes.instrument.visa
     qcodes.instrument.channel
+    qcodes.instrument.delegate
     qcodes.instrument.base
 
 
@@ -20,4 +21,5 @@ qcodes.instrument (Instruments)
 
    visa
    channel
+   delegate
    base

qcodes/instrument/delegate/delegate_channel_instrument.py

@@ -10,6 +10,8 @@ class DelegateChannelInstrument(DelegateInstrument):
 
     Example usage in instrument YAML:
 
+    .. code-block:: yaml
+
         switch:
             type: qcodes.instrument.delegate.DelegateChannelInstrument
             init:
@@ -21,15 +23,24 @@ class DelegateChannelInstrument(DelegateInstrument):
                     - gnd
                     - bus
 
-    The above will create a new instrument called "switch" that generates a
+    The above will create a new instrument called ``switch`` that generates a
     method for a delegate parameter:
+
+    .. code-block:: python
+
         switch.state()
 
     that returns a named tuple:
+
+    .. code-block:: python
+
         state(dac_output=..., smc=..., gnd=..., bus=...)
 
     where the values of each of the tuple items are delegated to the
     instrument parameters:
+
+    .. code-block:: python
+
         dac.dac_output()
         dac.smc()
         dac.gnd()

qcodes/instrument/delegate/delegate_instrument.py

@@ -22,37 +22,49 @@ class DelegateInstrument(InstrumentBase):
 
     Example usage in instrument YAML:
 
-    field:
-        type: qcodes.instrument.delegate.DelegateInstrument
-        init:
-        parameters:
-            X:
-                - field_X.field
-            ramp_rate:
-                - field_X.ramp_rate
-        set_initial_values_on_load: true
-        initial_values:
-            ramp_rate: 0.02
-        setters:
-            X:
-                method: field_X.set_field
-                block: false
-        units:
-            X: T
-            ramp_rate: T/min
+    .. code-block:: yaml
+
+        field:
+            type: qcodes.instrument.delegate.DelegateInstrument
+            init:
+            parameters:
+                X:
+                    - field_X.field
+                ramp_rate:
+                    - field_X.ramp_rate
+            set_initial_values_on_load: true
+            initial_values:
+                ramp_rate: 0.02
+            setters:
+                X:
+                    method: field_X.set_field
+                    block: false
+            units:
+                X: T
+                ramp_rate: T/min
 
     this will generate an instrument named "field" with methods:
+
+    .. code-block:: python
+
         field.X()
         field.ramp_rate()
 
     that are delegate parameters for:
+
+    .. code-block:: python
+
         field_X.field()
         field_X.ramp_rate()
 
-    Additionally, this will set field_X.ramp_rate(0.02) on load and
-    override the field.X.set() method with
+    Additionally, this will set ``field_X.ramp_rate(0.02)``` on load and
+    override the ``field.X.set()`` method with
+
+    .. code-block:: python
+
         field_X.set_field(value, block=False),
-    as opposed to field.X.field.set() which ramps with block=True.
+
+    as opposed to ``field.X.field.set()`` which ramps with ``block=True``.
 
     Args:
         name: Instrument name
@@ -64,7 +76,7 @@ class DelegateInstrument(InstrumentBase):
             parameters. Defaults to None.
         set_initial_values_on_load: Flag to set initial values when the
             instrument is loaded. Defaults to False.
-        setters: Optional setter methods to use instead of calling the .set()
+        setters: Optional setter methods to use instead of calling the ``.set()``
             method on the endpoint parameters. Defaults to None.
         units: Optional units to set for parameters.
         metadata: Optional metadata to pass to instrument. Defaults to None.

qcodes/instrument/delegate/grouped_parameter.py

@@ -4,14 +4,13 @@
     Dict,
     Iterable,
     Optional,
-    OrderedDict,
     Tuple,
     Union,
     Sequence,
     Callable,
     TYPE_CHECKING
 )
-from collections import namedtuple
+from collections import namedtuple, OrderedDict
 from qcodes.instrument.parameter import (
     DelegateParameter,
     ParamDataType,
@@ -46,33 +45,33 @@ def __init__(
 
 
 class DelegateGroup(Group):
-    """The DelegateGroup combines :class:`.DelegateParameter`s that
+    """The DelegateGroup combines :class:`.DelegateParameter` s that
     are to be gotten or set using one :class:`.GroupedParameter`.
     Each :class:`.DelegateParameter` maps to one source parameter
     that is individually set or gotten on an instrument. These
     parameters can originate from the same or different instruments.
 
     The class :class:`.DelegateGroup` is used within the
     :class:`GroupedParameter` class in order to get and set the
-    :class:`.DelegateParameter`s either via their default get and set
+    :class:`.DelegateParameter` s either via their default get and set
     methods or via a custom get or set method.
 
     The value to be set can be passed to the set method either via a
     dictionary, where the keys are the names of the
-    :class:`.DelegateParameter`s contained in the :class:`DelegateGroup`,
+    :class:`.DelegateParameter` s contained in the :class:`DelegateGroup`,
     or a single value, if a custom setter is defined or if the group
     only contains a single :class:`.DelegateParameter`.
 
     The value returned by the get method is passed through a formatter.
     By default, the formatter returns the :class:`.DelegateParameter`
     values in a namedtuple, where the keys are the names of the
-    :class:`.DelegateParameter`s. In the special case where the
+    :class:`.DelegateParameter` s. In the special case where the
     :class:`.DelegateGroup` only contains one :class:`.DelegateParameter`,
     the formatter simply returns the individual value. Optionally,
     the formatter can be customized and specified via the constructor.
-    The formatter takes as input the values of the :class:`.DelegateParameter`s
+    The formatter takes as input the values of the :class:`.DelegateParameter` s
     as positional arguments in the order at which the
-    :class:`.DelegateParameter`s are specified.
+    :class:`.DelegateParameter` s are specified.
 
     Args:
         name: Name of the DelegateGroup
@@ -157,12 +156,12 @@ def source_parameters(self) -> Tuple[Optional[Parameter], ...]:
 
 class GroupedParameter(_BaseParameter):
     """
-    The GroupedParameter wraps one or more :class:`.DelegateParameter`s,
+    The GroupedParameter wraps one or more :class:`.DelegateParameter` s,
     such that those parameters can be accessed as if they were one
     parameter.
 
     The :class:`GroupedParameter` uses a :class:`DelegateGroup` to keep
-    track of the :class:`.DelegateParameter`s. Mainly, this class is a
+    track of the :class:`.DelegateParameter` s. Mainly, this class is a
     thin wrapper around the :class:`DelegateGroup`, and mainly exists
     in order to allow for it to be used as a :class:`_BaseParameter`.
 

qcodes/instrument/delegate/instrument_group.py

@@ -13,7 +13,7 @@ class InstrumentGroup(InstrumentBase):
     InstrumentGroup is an instrument driver to represent a series of instruments
     that are grouped together. This instrument is mainly used as a wrapper for
     sub instruments/submodules and particularly built for use with grouping
-    multiple :class:`DelegateInstrument`s.
+    multiple :class:`DelegateInstrument` s.
 
     Args:
         name: Name referring to this group of items