Merge pull request #29 from pbnjeff89/master

Documentation updates

docs/contributing.rst

@@ -3,26 +3,16 @@ Contributing new drivers
 #########################
 
 Each driver is implemented as a class named after the corresponding instrument.
-Each class contains the broadest subset of the following components
-which makes sense for the given instrument type::
-
-    - a read_point() method which reads a single point using the current instrument configuration
-
-    - a set of get_<parameter> and set_<parameter> methods which query and specify the instrument configuration, respectively
-
-    - a pandas DataFrame which stores data collected by the instrument
-
-The driver classes are intended to be used directly (for example, as part
-of a Jupyter notebook-based workflow), therefore simplicity is prioritized
-over completeness.
+The driver classes are intended to be used directly and usable by anyone who decides to use
+these for experiment.
 
 ^^^^^^^^^^^^^^^^^^
 Coding conventions
 ^^^^^^^^^^^^^^^^^^
 
-The drivers in the labdrivers package follow the following conventions:
+The modules in the `labdrivers` package follow the following conventions:
 
-- Class names are all CamcelCase, e.g.::
+- Class names are all CamelCase, e.g.::
 
     Keithley2400
     Sr830
@@ -35,17 +25,18 @@ The drivers in the labdrivers package follow the following conventions:
     auto_gain
     set_output_voltage
 
+Depending on the future of the use of the `labdrivers` package, the coding conventions may be revised
+to maintain consistency.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Driver design principles
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-
 - Minimize the amount of 'internal state' maintained by the driver
 
-Wherever possible, implement methods which query the instrument about
-its status instead of attributes which track the instrument's status
-within the driver class.
+The only 'internal state' that an instance should keep are properties like an IP address
+or a GPIB resource name. Most classes use the property decorator, but they are used only
+to make a query and return the response directly to the user.
 
 E.g. do this::
 
@@ -61,31 +52,35 @@ instead of this::
     def getOutput():
         return self.output
 
+- Use property decorators when possible to avoid writing getter and setter methods
 
-- Limit the number of :code:`get_<parameter>` and :code:`set_<parameter>` methods
-
-For instrument parameters which take a finite set of categorical variables 
-(for example the output of a digital multimeter, which can be set to source
-either current or voltage) create a single function that takes the 
-categorical variable as its first argument.
+- Use function names that are intuitive and minimize the amount of input required.
 
 E.g. do this::
 
-    def set_output(self, source_type, source_level):
-        ...
+    def output_current(self, current):
+        thing.output('current', current)
 
-instead of this::
-
-    def set_output_voltage(self, source_level):
-        ...
-
-    def set_output_current(self, source_level):
-        ...
+    def output_voltage(self, voltage):
+        thing.output('voltage', voltage)
 
+It might be more "efficient" to just allow for two inputs, but generally it would be less confusing
+if there were only one input. This is a change from older versions of `labdrivers` (0.8.x and below?).
 
 ^^^^^^^^^^^^^^^^^^^^^^^
 Documenting drivers
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Each method in the driver should be documented using a "`Google style <http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html>`_"
-docstring. Check the existing source code for examples.
+Each method in the driver should be documented using a the reStructuredText format.
+
+Example::
+
+    """
+    First line of documentation.
+
+    :param thing1: Description of thing1 parameter
+    :param thing2: Description of thing2 parameter
+    :returns: Description of the returned data
+    :raises SomeError: Description of when SomeError shows up
+    """
+

docs/index.rst

@@ -21,22 +21,22 @@ implements the driver.
 
 Currently labdrivers contains drivers for the following instruments::
 
-	labdrivers/
-	|-- keithley
-	    `-- keithley2400.py
-	|-- lakeshore
-	    `-- ls332.py
-	|-- ni
-	    `-- nidaq.py
-	|-- oxford
-	    |-- itc503.py
-	    |-- ips120.py
-		|-- mercuryips.py
-		`-- triton200.py
-	|-- quantumdesign
-	    `-- qdinstrument.py
-	|-- srs
-	    `-- sr830.py
+   labdrivers/
+   |-- keithley
+       `-- keithley2400.py
+   |-- lakeshore
+       `-- ls332.py
+   |-- ni
+       `-- nidaq.py
+   |-- oxford
+       |-- itc503.py
+       |-- ips120.py
+       |-- mercuryips.py
+       `-- triton200.py
+   |-- quantumdesign
+       `-- qdinstrument.py
+   |-- srs
+       `-- sr830.py
 
 So for example, to load the driver for a Keithley 2400 SMU::
 

docs/labdrivers.lakeshore.rst

@@ -0,0 +1,11 @@
+##########################
+labdrivers.lakeshore
+##########################
+
+.. toctree::
+   :maxdepth: 1
+
+
+.. autoclass:: labdrivers.lakeshore.ls332.Ls332
+    :members:
+    :undoc-members: