Boiler plate doc files creation. Outlines basic documentation structure

dihm · dihm · commit bc525a1f8190 · 2021-05-31T12:23:53.000-04:00
to cover all the devices as well as some higher level stuff.
diff --git a/docs/source/adding_devices.rst b/docs/source/adding_devices.rst
@@ -0,0 +1,2 @@
+How to Add a Device
+===================
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -39,6 +39,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
@@ -49,6 +50,7 @@
 ]
 
 autodoc_typehints = 'description'
+autoclass_content = 'init'
 
 # Prefix each autosectionlabel with the name of the document it is in and a colon
 autosectionlabel_prefix_document = True
diff --git a/docs/source/devices.rst b/docs/source/devices.rst
@@ -0,0 +1,83 @@
+Devices
+=========
+
+Here is a list of all the currently supported devices.
+
+
+Pseudoclocks
+~~~~~~~~~~~~
+
+Pseudoclocks provide the timing backbone of the labscript_suite. These devices produce hardware-timed clocklines that trigger other device outputs and acquisitions. Many pseudoclock devices also include other types of outputs, including digital voltage and DDS frequency synthesizers.
+
+.. toctree::
+   :maxdepth: 2
+
+   devices/pulseblaster
+   devices/pulseblaster_no_dds
+   devices/opalkellyXEM3001
+   devices/pineblaster
+   devices/rfblaster
+
+NI DAQS
+~~~~~~~~~~~~
+
+The NI_DAQmx device provides a generic interface for National Instruments data acquisition hardware. This includes digital and analog voltage I/O. These input/outputs can be either static or hardware-timed dynamically changing variables.
+
+.. toctree::
+   :maxdepth: 2
+
+   devices/ni_daqs
+
+Cameras
+~~~~~~~~~~~~
+
+The camera devices provide interfaces for using various scientific cameras to acquire hardware-timed images during an experiment. They are organized by the programming API the underlies the communication to the device. The "master" camera class which provides the core functionality and from which the others derive is the IMAQdx class.
+
+.. toctree::
+   :maxdepth: 2
+
+   devices/IMAQdx
+   devices/pylon
+   devices/flycapture2
+   devices/andorsolis
+
+
+Frequency Sources
+~~~~~~~~~~~~~~~~~
+
+These devices cover various frequency sources that provide either hardware-timed frequency, amplitude, or phase updates or static frequency outputs.
+
+.. toctree::
+   :maxdepth: 2
+
+   devices/novatechDDS9m
+   devices/phasematrixquicksyn
+
+
+Miscellaneous
+~~~~~~~~~~~~~~~
+
+These devices cover other types of devices.
+
+.. toctree::
+   :maxdepth: 2
+
+   devices/alazartechboard
+   devices/lightcrafterdmd
+   devices/tekscope
+   devices/zaberstagecontroller
+
+
+Other
+~~~~~~~~~~~~~~
+
+These devices provide dummy instruments for prototyping and testing purposes of the rest of the labscript_suite as well as the FunctionRunner device which can run arbitrary code post-shot.
+
+.. toctree::
+   :maxdepth: 2
+
+   devices/functionrunner
+   devices/dummypseudoclock
+   devices/dummyintermediate
+   devices/testdevice
+   
diff --git a/docs/source/devices/IMAQdx.rst b/docs/source/devices/IMAQdx.rst
@@ -0,0 +1,2 @@
+IMAQdx Cameras
+==============
diff --git a/docs/source/devices/alazartechboard.rst b/docs/source/devices/alazartechboard.rst
@@ -0,0 +1,2 @@
+Alazar Tech Board
+=================
diff --git a/docs/source/devices/andorsolis.rst b/docs/source/devices/andorsolis.rst
@@ -0,0 +1,2 @@
+Andor Solis Cameras
+===================
diff --git a/docs/source/devices/dummyintermediate.rst b/docs/source/devices/dummyintermediate.rst
@@ -0,0 +1,2 @@
+Dummy Intermediate Device
+=========================
diff --git a/docs/source/devices/dummypseudoclock.rst b/docs/source/devices/dummypseudoclock.rst
@@ -0,0 +1,2 @@
+Dummy Pseudoclock
+=================
diff --git a/docs/source/devices/flycapture2.rst b/docs/source/devices/flycapture2.rst
@@ -0,0 +1,2 @@
+FlyCapture2 Cameras
+===================
diff --git a/docs/source/devices/functionrunner.rst b/docs/source/devices/functionrunner.rst
@@ -0,0 +1,2 @@
+Function Runner
+===============
diff --git a/docs/source/devices/lightcrafterdmd.rst b/docs/source/devices/lightcrafterdmd.rst
@@ -0,0 +1,2 @@
+Light Crafter DMD
+=================
diff --git a/docs/source/devices/ni_daqs.rst b/docs/source/devices/ni_daqs.rst
@@ -0,0 +1,2 @@
+NI DAQS
+=======
diff --git a/docs/source/devices/novatechDDS9m.rst b/docs/source/devices/novatechDDS9m.rst
@@ -0,0 +1,2 @@
+Novatech DDS 9m
+===============
diff --git a/docs/source/devices/opalkellyXEM3001.rst b/docs/source/devices/opalkellyXEM3001.rst
@@ -0,0 +1,2 @@
+Cicero Opal-Kelly XEM3001
+=========================
diff --git a/docs/source/devices/phasematrixquicksyn.rst b/docs/source/devices/phasematrixquicksyn.rst
@@ -0,0 +1,2 @@
+Phase Matrix Quick Synthesizer
+==============================
diff --git a/docs/source/devices/pineblaster.rst b/docs/source/devices/pineblaster.rst
@@ -0,0 +1,2 @@
+Pineblaster
+===========
diff --git a/docs/source/devices/pulseblaster.rst b/docs/source/devices/pulseblaster.rst
@@ -0,0 +1,2 @@
+Pulseblaster
+============
diff --git a/docs/source/devices/pulseblaster_no_dds.rst b/docs/source/devices/pulseblaster_no_dds.rst
@@ -0,0 +1,2 @@
+Pulseblaster (-DDS)
+===================
diff --git a/docs/source/devices/pylon.rst b/docs/source/devices/pylon.rst
@@ -0,0 +1,49 @@
+Pylon Cameras
+=============
+
+Overview
+~~~~~~~~
+
+This device allows control of Basler scientific cameras via the `Pylon API <https://docs.baslerweb.com/pylon-camera-software-suite>`_ with the `PyPylon python wrapper <https://pypi.org/project/pypylon/>`_. In order to use this device, both the Basler Pylon API and the PyPylon wrapper must be installed.
+
+.. autosummary::
+   labscript_devices.PylonCamera.labscript_devices
+   labscript_devices.PylonCamera.blacs_tabs
+   labscript_devices.PylonCamera.blacs_workers
+   labscript_devices.PylonCamera.register_classes
+
+Installation
+~~~~~~~~~~~~
+
+Detailed Documentation
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: labscript_devices.PylonCamera
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+
+.. automodule:: labscript_devices.PylonCamera.labscript_devices
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+
+.. automodule:: labscript_devices.PylonCamera.blacs_tabs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+
+.. automodule:: labscript_devices.PylonCamera.blacs_workers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+
+.. automodule:: labscript_devices.PylonCamera.register_classes
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
diff --git a/docs/source/devices/rfblaster.rst b/docs/source/devices/rfblaster.rst
@@ -0,0 +1,2 @@
+RFblaster
+=========
diff --git a/docs/source/devices/tekscope.rst b/docs/source/devices/tekscope.rst
@@ -0,0 +1,2 @@
+Tektronix Oscilloscope
+======================
diff --git a/docs/source/devices/testdevice.rst b/docs/source/devices/testdevice.rst
@@ -0,0 +1,2 @@
+Test Device
+===========
diff --git a/docs/source/devices/zaberstagecontroller.rst b/docs/source/devices/zaberstagecontroller.rst
@@ -0,0 +1,2 @@
+Zaber Stage Controller
+======================
diff --git a/docs/source/ex_conn_tables.rst b/docs/source/ex_conn_tables.rst
@@ -0,0 +1,2 @@
+Example Connection Tables
+=========================
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -11,7 +11,11 @@ labscript-devices
    :hidden:
    :caption: DOCUMENTATION
 
-   
+   introduction
+   devices
+   user_devices
+   ex_conn_tables
+   adding_devices
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
@@ -0,0 +1,24 @@
+Introduction
+============
+
+The **labscript_devices** module contains the low-level hardware interfacing code that intermediates between the :doc:`labscript <labscript:index>` API (converting **labscript** instructions into hardware instructions) as well as the :doc:`BLACS <blacs:index>` GUI (which communicates directly with the hardware).
+
+Each "device" is made up of four classes that handle the various tasks.
+
+* `labscript_device` (derives from :doc:`labscript.Device <labscript:api/device>`)
+
+   - Defines the interface between the **labscript** API and generates hardware instructions that can be saved to the shot h5 file.
+
+* `BLACS_tab` (derives from :doc:`blacs.device_base_class.DeviceTab <blacs:index>`)
+
+   - Defines the graphical tab that is present in the **BLACS** GUI. This tab provides graphical widgets for controlling hardware outputs and visualizing hardware inputs.
+
+* `BLACS_worker` (derives from :doc:`blacs.tab_base_classes.Worker <blacs:index>`)
+
+   - Defines the software control interface to the hardware. The `BLACS_tab` spawns a process that uses this class to send and receive commands with the hardware.
+
+* `runviewer_parser`
+
+   - Defines a software interface that interprets hardware instructions in a shot h5 file and displays them in the :doc:`runviewer <runviewer:index>` GUI.
+
+The **labscript_suite** provides an extensive :doc:`list of device classes <devices>` for commercially available hardware. Furthermore, it is simple to add local :doc:`user devices <user_devices>` to control instruments not already within the labscript-suite.
diff --git a/docs/source/user_devices.rst b/docs/source/user_devices.rst
@@ -0,0 +1,2 @@
+User Devices
+============

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+How to Add a Device`
	`2`	`+===================`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Alazar Tech Board`
	`2`	`+=================`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Andor Solis Cameras`
	`2`	`+===================`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Dummy Intermediate Device`
	`2`	`+=========================`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Dummy Pseudoclock`
	`2`	`+=================`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+FlyCapture2 Cameras`
	`2`	`+===================`