Documentation location

[MatthieuDartiailh]

While starting to write some docs for lantz_core I realized, that save for the very specific documentation concerning the internals of the system, it was not really making sense to document a number of things in lantz_core as basically using it alone without the drivers make no sense.
Specifically accessing a driver, instantiating it and using it belongs in lantz_drivers but defining the unit registry, setting global parameters (such UnitRegistry, ResourceManagers for the visa backend, etc) are in the core.
Should we have a generic purpose manual (installation, basic usage, configuration, writing drivers (as in this both drivers and core are interleaved), etc) and then cross-references to each package doc for the technical points (understanding Feature/channel/subsystem inner working) ?

[vascotenner]

I think a general purpose manual/tutorial is very usefull. Lantz is a rich system, where many things are happening "automagically". Many of these things are not easy to find out from only reading the docstrings.

I would say that the doc of the driver repro should only contain "apparatus"-driver specific documentation. All the possible features and standard practices around drivers should be documented in core (maybe with references to specific drivers for examples of the specific feature).

[JesterEE]

I agree with vascotenner. The original Lantz docs did a decent job of this. Showing off the features of the system in a few page tutorial was extremely useful to get going. However, I do think it's important to show the "right" way to write a driver. IMO it's not useful to say go look at X driver and do something similar. People will look at the driver, make assumptions to what is actually going on, and at the end of the day there will lots of user drivers that may not live up to expectations because the dev didn't really understand how to implement the hardware features effectively.

If I were writing a labpy driver (which I will be doing) I'd want to see the following:

1. An overview/tutorial of the most common features.
2. A more in depth dive to describe what's actually going on (where the code does what and what it looks for)
3. A document or 2 explaining example drivers. Maybe one simple driver like a DC source and maybe one more complicated driver like an oscilloscope/spectrum analyzer/AWG that have channels, math functions, measurement modes, configuration options, etc.