Get action descriptions from docstrings

openflexure_microscope/api/v2/blueprints/actions/__init__.py

@@ -1,45 +1,41 @@
 from flask import Blueprint, url_for, jsonify
 from sys import platform
 
+from openflexure_microscope.utilities import get_docstring
 from openflexure_microscope.api.views import MicroscopeView
 
 from . import camera, stage, system
 
+
 _actions = {
     "capture": {
         "rule": "/camera/capture/",
         "view_class": camera.CaptureAPI,
-        "description": "Take a single still capture",
         "conditions": True,
     },
     "preview_start": {
         "rule": "/camera/preview/start",
         "view_class": camera.GPUPreviewStartAPI,
-        "description": "Start the on-board GPU preview",
         "conditions": True,
     },
     "preview_stop": {
         "rule": "/camera/preview/stop",
         "view_class": camera.GPUPreviewStopAPI,
-        "description": "Stop the on-board GPU preview",
         "conditions": True,
     },
     "move": {
         "rule": "/stage/move/",
         "view_class": stage.MoveStageAPI,
-        "description": "Move the microscope stage",
         "conditions": True,
     },
     "shutdown": {
         "rule": "/system/shutdown/",
         "view_class": system.ShutdownAPI,
-        "description": "Shutdown the device",
         "conditions": (platform == "linux"),
     },
     "reboot": {
         "rule": "/system/reboot/",
         "view_class": system.RebootAPI,
-        "description": "Reboot the device",
         "conditions": (platform == "linux"),
     },
 }
@@ -57,7 +53,7 @@ def actions_representation():
     for name, action in enabled_actions().items():
         d = {
             "links": {"self": url_for(f".{name}")},
-            "description": action["description"],
+            "description": get_docstring(action["view_class"]),
             "rule": action["rule"],
             "view_class": str(action["view_class"]),
         }

openflexure_microscope/api/v2/blueprints/actions/camera.py

@@ -7,6 +7,12 @@ from flask import jsonify, request, abort, url_for, redirect, send_file
 
 
 class CaptureAPI(MicroscopeView):
+    """
+    Create a new image capture. 
+    
+    Allowed methods: 
+        POST
+    """
     def post(self):
         """
         Create a new image capture.
@@ -101,6 +107,12 @@ class CaptureAPI(MicroscopeView):
 
 
 class GPUPreviewStartAPI(MicroscopeView):
+    """
+    Start the onboard GPU preview.
+    
+    Allowed methods: 
+        POST
+    """
     def post(self, operation):
         """
         Start the onboard GPU preview.
@@ -143,6 +155,12 @@ class GPUPreviewStartAPI(MicroscopeView):
 
 
 class GPUPreviewStopAPI(MicroscopeView):
+    """
+    Stop the onboard GPU preview.
+    
+    Allowed methods: 
+        POST
+    """
     def post(self, operation):
         """
         Stop the onboard GPU preview.

openflexure_microscope/api/v2/blueprints/actions/stage.py

@@ -8,6 +8,12 @@ import logging
 
 
 class MoveStageAPI(MicroscopeView):
+    """
+    Handle stage movements. 
+    
+    Allowed methods: 
+        POST
+    """
     def post(self):
         """
         Set x, y and z positions of the stage.

openflexure_microscope/api/v2/blueprints/actions/system.py

@@ -4,6 +4,12 @@ import subprocess
 
 
 class ShutdownAPI(MicroscopeView):
+    """
+    Attempt to shutdown the device 
+    
+    Allowed methods: 
+        POST
+    """
     def post(self):
         """
         Attempt to shutdown the device
@@ -17,6 +23,12 @@ class ShutdownAPI(MicroscopeView):
 
 
 class RebootAPI(MicroscopeView):
+    """
+    Attempt to reboot the device 
+    
+    Allowed methods: 
+        POST
+    """
     def post(self):
         """
         Attempt to shutdown the device

openflexure_microscope/api/v2/blueprints/plugins.py

@@ -1,5 +1,6 @@
 from openflexure_microscope.plugins import PluginLoader, MicroscopePlugin
 from openflexure_microscope.api.views import MicroscopeViewPlugin
+from openflexure_microscope.utilities import get_docstring
 
 from flask import Blueprint, jsonify, url_for
 from openflexure_microscope.api.views import MicroscopeView
@@ -28,7 +29,7 @@ def plugins_representation(plugin_loader_object: PluginLoader):
             "plugin": str(plugin),
             "views": {},
             "form": plugin.form,
-            "description": plugin.__doc__.strip() if plugin.__doc__ else ""
+            "description": get_docstring(plugin)
         }
 
         for view_id, view_data in plugin.views.items():
@@ -36,7 +37,7 @@ def plugins_representation(plugin_loader_object: PluginLoader):
             uri = url_for(f"v2_plugins_blueprint.{view_id}")
             # Make links dictionary if it doesn't yet exist
             view_d = {
-                "description": view_data["view"].__doc__.strip() if view_data["view"].__doc__ else "",
+                "description": get_docstring(view_data["view"]),
                 "links": {"self": uri}
             }
 

openflexure_microscope/utilities.py

@@ -5,6 +5,12 @@ from collections import abc
 from functools import reduce
 from contextlib import contextmanager
 
+def get_docstring(obj):
+    ds = obj.__doc__
+    if ds:
+        return ds.strip()
+    else:
+        return ""
 
 def camel_to_snake(name):
     s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)