Squashed commit of the following:

commit c054099 Author: David Meyer <dihm@users.noreply.github.com> Date: Tue Dec 7 10:26:22 2021 -0500 Update setup.cfg to show python 3.9 support commit d1ee324 Merge: dbeccbc ce11661 Author: David Meyer <dihm@users.noreply.github.com> Date: Tue Nov 30 12:42:32 2021 -0500 Merge pull request #79 from philipstarkey/break-circular-dependency Updated BLACS to use the new labscript-utils device registry. commit ce11661 Merge: 741d790 dbeccbc Author: David Meyer <dihm@users.noreply.github.com> Date: Tue Nov 30 12:39:25 2021 -0500 Merge branch 'master' into break-circular-dependency commit dbeccbc Merge: 641cdeb 7f9552a Author: David Meyer <dihm@users.noreply.github.com> Date: Wed Nov 24 11:22:29 2021 -0500 Merge pull request #87 from zakv/fix-86 Fixed issue where blacs couldn't close with certain tabs commit 641cdeb Merge: e8bdd1b ff6f447 Author: David Meyer <dihm@users.noreply.github.com> Date: Wed Nov 10 16:57:14 2021 -0500 Merge pull request #81 from zakv/conversion-import-error Fix Bug in AO.__init__() When Unit Conversion Import Fails commit e8bdd1b Merge: b083bb8 868b991 Author: David Meyer <dihm@users.noreply.github.com> Date: Fri Jul 16 16:06:03 2021 -0400 Merge pull request #80 from dihm/blacs-docs Initial pass at BLACS docs commit 868b991 Author: David Meyer <dihm.meyer@gmail.com> Date: Thu Jul 15 10:37:40 2021 -0400 Add docstring coverage check to build. commit ce2c490 Author: David Meyer <dihm.meyer@gmail.com> Date: Thu Jul 15 10:37:15 2021 -0400 Update sphinx pin. commit a3e6040 Author: David Meyer <dihm.meyer@gmail.com> Date: Fri Jul 9 12:05:25 2021 -0400 Add unlisted dependency in `compile_and_restart` on runmanager. commit 2c0ec0c Author: David Meyer <dihm.meyer@gmail.com> Date: Fri Jul 9 11:57:36 2021 -0400 Add missing import to conf.py commit 03a53e2 Author: David Meyer <dihm.meyer@gmail.com> Date: Fri Jul 9 11:55:06 2021 -0400 Add API documentation for the BLACS GUI. commit 869d28f Author: David Meyer <dihm.meyer@gmail.com> Date: Fri Jul 9 11:52:38 2021 -0400 Version bump sphinx to match rest of modules. commit 06539c4 Author: David Meyer <dihm.meyer@gmail.com> Date: Tue Nov 17 19:41:19 2020 -0500 Updating high level docs from @philipstarkey Thesis. commit d542c2f Author: David Meyer <dihm.meyer@gmail.com> Date: Tue Nov 17 17:27:25 2020 -0500 Add API documentation for the blacs submodules. Relies on recursive autosummary and a custom template. In testing builds, noticed that experiment_queue and plugins depended on a properly set up labconfig; namely experiment_shot_storage. Might be an issue on readthedocs. commit 057d849 Author: David Meyer <dihm.meyer@gmail.com> Date: Tue Nov 17 17:03:41 2020 -0500 Add pyqt5 intersphinx inventory. commit b083bb8 Merge: 2bd2aa6 3930ffc Author: chrisjbillington <chrisjbillington@gmail.com> Date: Fri Apr 9 12:27:24 2021 +1000 Merge branch 'dihm/setuptools_scm-fix' commit 3930ffc Author: chrisjbillington <chrisjbillington@gmail.com> Date: Fri Apr 9 12:26:48 2021 +1000 * Continue to set local scheme based on env var in `__version__.py` for consistency. * Don't require specific setuptools or [toml] extra from setuptools_scm. We aren't configuring setuptools_scm in pyproject.toml anyway, and setuptools_scm itself will specify a fairly recent version of setuptools (we have no special requirement ourselves) * no longer use env var for version_scheme in setup.py, since we're now hard-coding release-branch-semver. commit 75b10aa Author: David Meyer <dihm.meyer@gmail.com> Date: Fri Apr 2 13:50:25 2021 -0400 Update setup.cfg Adds setuptools-scm with required version. commit feff404 Author: David Meyer <dihm.meyer@gmail.com> Date: Tue Dec 29 14:22:20 2020 -0500 Update default setuptools_scm version scheme to release-branch-semver. This fixes the circular dependency issue between blacs and labscript-devices. commit 7f9552a Author: Zak V <zakven@mit.edu> Date: Fri Jan 15 08:23:51 2021 -0500 Fixed issue where blacs couldn't close if a tab doesn't have shutdown_workers() and finalise_close_tab() methods. In particular, PluginTab doesn't have these methods. commit 2bd2aa6 Merge: 0e153f2 ca203a4 Author: Chris Billington <chrisjbillington@gmail.com> Date: Tue Jan 5 13:55:02 2021 +1100 Merge pull request #85 from zakv/fix-84 Fix copy/paste bug where stop_order is set to start_order commit ca203a4 Author: Zak V <zakven@mit.edu> Date: Mon Jan 4 21:16:06 2021 -0500 Fixed copy/paste bug where stop_order was set to start_order in QueueManager.manage(). commit ff6f447 Author: Zak V <zakven@mit.edu> Date: Tue Nov 24 17:30:12 2020 -0500 Corrected mistaken change to AO.__init__() error message in previous commit. commit e0a615a Author: Zak V <zakven@mit.edu> Date: Tue Nov 24 16:54:22 2020 -0500 Fixed bug in AO.__init__() where failure to import a unit conversion class wasn't reported correctly, causing "AttributeError: 'NoneType' object has no attribute 'base_unit'". commit 741d790 Author: philipstarkey <philipstarkey@users.noreply.github.com> Date: Thu Jul 16 17:17:02 2020 +1000 Updated BLACS to use the new labscript-utils device registry. Removes the circular dependency on labscript-devices. This update assumes we will publish a new labscript-utils beta (3.1.0b1) shortly (so will fail to build on RTD until that is done)
labscript-suite · Dec 7, 2021 · 7d9f74e · 7d9f74e
1 parent 0e153f2
commit 7d9f74e
Show file tree

Hide file tree

Showing 27 changed files with 729 additions and 24 deletions.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -15,7 +15,6 @@ defaults:
 
 env:
   PACKAGE_NAME: blacs
-  SCM_VERSION_SCHEME: release-branch-semver
   SCM_LOCAL_SCHEME: no-local-version
   ANACONDA_USER: labscript-suite
 

diff --git a/.gitignore b/.gitignore
@@ -158,4 +158,5 @@ conda_packages/
 # Sphinx documentation
 docs/html/
 docs/source/_build/
-docs/source/components.rst
+docs/source/components.rst
+docs/source/api/_autosummary
diff --git a/blacs/__main__.py b/blacs/__main__.py
@@ -10,6 +10,8 @@
 # the project for the full license.                                 #
 #                                                                   #
 #####################################################################
+'''BLACS GUI and supporting code
+'''
 import labscript_utils.excepthook
 
 import os
@@ -95,7 +97,7 @@
 # Queue Manager Code
 from blacs.experiment_queue import QueueManager, QueueTreeview
 # Module containing hardware compatibility:
-import labscript_devices
+from labscript_utils import device_registry
 # Save/restore frontpanel code
 from blacs.front_panel_settings import FrontPanelSettings
 # Notifications system
@@ -266,7 +268,7 @@ def __init__(self,application):
                 self.settings_dict[device_name]["saved_data"] = tab_data[device_name]['data'] if device_name in tab_data else {}
                 # Instantiate the device
                 logger.info('instantiating %s'%device_name)
-                TabClass = labscript_devices.get_BLACS_tab(labscript_device_class_name)
+                TabClass = device_registry.get_BLACS_tab(labscript_device_class_name)
                 self.tablist[device_name] = TabClass(self.tab_widgets[0],self.settings_dict[device_name])
             except Exception:
                 self.failed_device_settings[device_name] = {"front_panel": self.settings_dict[device_name]["front_panel_settings"], "save_data": self.settings_dict[device_name]["saved_data"]}
@@ -602,7 +604,9 @@ def on_save_exit(self):
         self.front_panel_settings.save_front_panel_to_h5(self.settings_path,data[0],data[1],data[2],data[3],{"overwrite":True},force_new_conn_table=True)
         logger.info('Shutting down workers')
         for tab in self.tablist.values():
-            tab.shutdown_workers()
+            # Tell tab to shutdown its workers if it has a method to do so.
+            if hasattr(tab, 'shutdown_workers'):
+                tab.shutdown_workers()
 
         QTimer.singleShot(100, self.finalise_quit)
 
@@ -616,6 +620,14 @@ def finalise_quit(self, deadline=None, pending_threads=None):
         overdue = time.time() > deadline
         # Check for worker shutdown completion:
         for name, tab in list(self.tablist.items()):
+            # Immediately close tabs that don't support finalise_close_tab()
+            if not hasattr(tab, 'finalise_close_tab'):
+                try:
+                    current_page = tab.close_tab(finalise=False)
+                except Exception as e:
+                    logger.error('Couldn\'t close tab:\n%s' % str(e))
+                del self.tablist[name]
+                continue
             fatal_error = tab.state == 'fatal error'
             if not tab.shutdown_workers_complete and overdue or fatal_error:
                 # Give up on cleanly shutting down this tab's worker processes:

diff --git a/blacs/__version__.py b/blacs/__version__.py
@@ -5,15 +5,14 @@
 except ImportError:
     import importlib_metadata
 
-VERSION_SCHEME = {
-    "version_scheme": os.getenv("SCM_VERSION_SCHEME", "guess-next-dev"),
-    "local_scheme": os.getenv("SCM_LOCAL_SCHEME", "node-and-date"),
-}
-
 root = Path(__file__).parent.parent
 if (root / '.git').is_dir():
     from setuptools_scm import get_version
-    __version__ = get_version(root, **VERSION_SCHEME)
+    __version__ = get_version(
+        root,
+        version_scheme="release-branch-semver",
+        local_scheme=os.getenv("SCM_LOCAL_SCHEME", "node-and-date"),
+    )
 else:
     try:
         __version__ = importlib_metadata.version(__package__)

diff --git a/blacs/experiment_queue.py b/blacs/experiment_queue.py
@@ -598,7 +598,7 @@ def restart_function(device_name):
                         )
                         devices_in_use[name] = self.BLACS.tablist[name]
                         start_order[name] = device_properties.get('start_order', None)
-                        stop_order[name] = device_properties.get('start_order', None)
+                        stop_order[name] = device_properties.get('stop_order', None)
 
                 # Sort the devices into groups based on their start_order and stop_order
                 start_groups = defaultdict(set)

diff --git a/blacs/output_classes.py b/blacs/output_classes.py
@@ -62,7 +62,7 @@ def __init__(self, hardware_name, connection_name, device_name, program_function
             if cls is None or not isinstance(calib_params, dict) or cls.base_unit != default_units:
                 # log an error:  
                 reason = ''
-                if calib_class is None:
+                if cls is None:
                     reason = f'The unit conversion class {calib_class} could not be imported. Ensure it is available on the computer running BLACS.'
                 elif not isinstance(calib_params, dict):
                     reason = 'The parameters for the unit conversion class are not a dictionary. Check your connection table code for errors and recompile it'

diff --git a/docs/source/_templates/autosummary-class.rst b/docs/source/_templates/autosummary-class.rst
@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/source/_templates/autosummary-module.rst b/docs/source/_templates/autosummary-module.rst
@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: autosummary-class.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: autosummary-module.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
@@ -0,0 +1,18 @@
+API Reference
+=============
+
+.. autosummary::
+    :toctree: _autosummary
+    :template: autosummary-module.rst
+    :recursive:
+
+    blacs.analysis_submission
+    blacs.compile_and_restart
+    blacs.device_base_class
+    blacs.experiment_queue
+    blacs.front_panel_settings
+    blacs.notifications
+    blacs.output_classes
+    blacs.plugins
+    blacs.tab_base_classes
+    blacs.__main__
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -10,6 +10,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import copy
 import os
 from pathlib import Path
 from m2r import MdInclude
@@ -39,6 +40,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
@@ -49,6 +51,26 @@
 ]
 
 autodoc_typehints = 'description'
+autosummary_generate = True
+numfig = True
+autodoc_mock_imports = ['labscript_utils']
+
+# mock missing site package methods
+import site
+mock_site_methods = {
+    # Format:
+    #   method name: return value
+    'getusersitepackages': '',
+    'getsitepackages': []
+}
+__fn = None
+for __name, __rval in mock_site_methods.items():
+    if not hasattr(site, __name):
+        __fn = lambda *args, __rval=copy.deepcopy(__rval), **kwargs: __rval
+        setattr(site, __name, __fn)
+del __name
+del __rval
+del __fn
 
 # Prefix each autosectionlabel with the name of the document it is in and a colon
 autosectionlabel_prefix_document = True
@@ -223,3 +245,43 @@ def setup(app):
                 img_path=img_path
             )
         )
+
+    # hooks to test docstring coverage
+    app.connect('autodoc-process-docstring', doc_coverage)
+    app.connect('build-finished', doc_report)
+
+
+members_to_watch = ['module', 'class', 'function', 'exception', 'method', 'attribute']
+doc_count = 0
+undoc_count = 0
+undoc_objects = []
+undoc_print_objects = False
+
+
+def doc_coverage(app, what, name, obj, options, lines):
+    global doc_count
+    global undoc_count
+    global undoc_objects
+
+    if (what in members_to_watch and len(lines) == 0):
+        # blank docstring detected
+        undoc_count += 1
+        undoc_objects.append(name)
+    else:
+        doc_count += 1
+
+
+def doc_report(app, exception):
+    global doc_count
+    global undoc_count
+    global undoc_objects
+    # print out report of documentation coverage
+    total_docs = undoc_count + doc_count
+    if total_docs != 0:
+        print(f'\nAPI Doc coverage of {doc_count/total_docs:.1%}')
+        if undoc_print_objects or os.environ.get('READTHEDOCS'):
+            print('\nItems lacking documentation')
+            print('===========================')
+            print(*undoc_objects, sep='\n')
+    else:
+        print('No docs counted, run \'make clean\' then rebuild to get the count.')