search

python-microscope / microscope

Python library for control of microscope devices, supporting hardware triggers and distribution of devices over the network for performance and flexibility.
https://www.python-microscope.org
GNU General Public License v3.0
69 stars 41 forks source link

Automated list of supported hardware. #147

Closed iandobbie closed 3 years ago

iandobbie commented 4 years ago

I think we should be able to automatically build a list of supported devices. We could define a standard comment field for a hardware device driver file. This could then be extracted and collated to build a list, or table of supported devices. Then each driver writer would be responsible for listing the supported devices but keeping the list up to date would be much simpler.

I suggest

Supported Hardware

device type: Camera

supported device: Andor iXon - version 1-3

supported device: Evolve Delta - version 3

Any thoughts?

carandraug commented 4 years ago

I don't think this is a good idea, or at least not for now and on this form.

What we have now is a list of supported hardware on doc/supported-devices.py. Shifting that information to the class/module won't make it any simpler. It will be pretty much the same amount of typing. It will, however, require that we create something that will extract that information from the module and create documentation from it. This is both work that we need to have now and more code to maintain in the future, and I don't see what work will save us from.

One possible advantage is that by having this information on the same file, whoever makes the changes to a module is more likely to remember updating its documentation accordingly. However, my experience is that this will not happen. I have seen, both in cockpit and microscope, comments that don't make sense because they pertain to lines that have since been changed. If we can't remember to adjust the comments that are on the line above, I don't have any hopes that we will remember adjusting the comments at the top of the file.

Also, most of our classes wrap a very large group of devices. For example, our XimeaCamera is supposed to support all ximea camera, not a subset of models. Our support of, of lack of support, for some models, is more likely to be due to the version of the upstream library we wrap than on our own code. In addition, the type of support information that we need to display to users is much more complex than just a list of models, we will need something more akin to the Wine Application Database (AppDB) where we can list the level of support for different models with different versions of both microscope and the upstream library (when applicable). It's not enough to say if something is supported, it may be supported with caveats, or missing some features.

What I have done so far, is to list the caveats on the module or class docstring (which is built automatically) and is linked from the doc/supported-devices.py. For example, the supported devices page mentions the Lumencor Spectra which links to the microscope.controllers.lumencor module page which then has a note block talking about standard vs legacy communication mode and another about requiring setting reference values on the device.

iandobbie commented 4 years ago

All good points. It seemed like a good idea yesterday. How about we add a comment to the developers documentation asking people to update the supported devices list if they add/change/remove devices.

carandraug commented 4 years ago

How about we add a comment to the developers documentation asking people to update the supported devices list if they add/change/remove devices.

Yes, we need to have that. I would put it as part of an howto on how to add support for a new device.

iandobbie commented 3 years ago

Added a comment to the get-involved/new-device.rst. Closing