Release 2.12.0

docs/README.md

@@ -0,0 +1,97 @@
+# LabOne Q documentation
+
+This subdirectory contains the documentation for LabOneQ.
+
+The last released version can be found here: https://docs.zhinst.com/labone_q_user_manual
+
+## Development
+
+The Documentation is generated with [MkDocs](https://www.mkdocs.org/) and 
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme
+to generate the documentation.
+
+### Build the documentation locally
+
+MkDocs is build with python, making it easy to install all requirement with `pip`.
+The documentation therefore has its own `requirements.txt` 
+
+Inside the `docs` directory, execute:
+
+```
+pip install requirements.txt
+```
+
+After this you should be able to build the documentation with:
+
+```
+mkdocs build
+```
+
+MkDocs also comes with a handy live preview that automatically adapts to your
+local changes.
+
+```
+mkdocs serve
+```
+
+### Structure
+The documentation is structured in four parts: 
+
+* `content/`: contains all markdown source files
+* `mkdocs.yml`: Configuration file for MKDocs. __INCLUDING__ the navigation content
+* `overrides`: Theme customization
+* `gen_file/`: Python script that are used in combination with the
+    [gen-files](https://oprypin.github.io/mkdocs-gen-files/) plugin
+
+### Automatic package reference documentation
+
+The package documentation is currently divided into two parts.
+
+[mkdocstrings](https://mkdocstrings.github.io/) is used to automatically
+generate the documentation for each element.
+
+[gen-files](https://oprypin.github.io/mkdocs-gen-files/) is used to automatically
+create the markdown files with the mkdocstrings identifiers.
+`docs/gen-files/reference_doc.py` is used as a prebuild script for gen-files.
+
+To keep the live preview responsive mkdocstrings is disabled by default. 
+The environment variable MKDOCSTRINGS, which takes a boolean value, can
+be used to enable the plugin. 
+
+Linux/Mac
+
+```
+(export MKDOCSTRINGS=true; mkdocs serve)
+```
+
+Windows
+
+```
+set "MKDOCSTRINGS=true" && mkdocs serve
+```
+
+### Jupyter notebook integration
+
+[mkdocs-jupyter](https://github.com/danielfrg/mkdocs-jupyter) is used to
+include jupyter notebooks into the documentation.
+
+In order to avoid copying all notebooks into the content directory, a simple 
+prebuild script `docs/gen-files/external_link.py` is used. It allows having
+placeholders for additional files that automatically get added during the 
+build step without the need of a symbolic link.
+
+### Additional notes
+
+Currently, we use
+[`use_directory_urls= True`](https://www.mkdocs.org/user-guide/configuration/#use_directory_urls)m
+which is the default. This means that if one views the static build sources in
+a browser, links will not work properly. 
+To view the static build sources locally, one needs to spin up a web server.
+Thankfully, this is quite easy in python:
+
+In the terminal, simply execute
+```
+python -m http.server -d path/to/static/sources
+```
+
+

examples/00_reference/00_session_reference.ipynb

@@ -254,7 +254,7 @@
    "id": "c6460f9b",
    "metadata": {},
    "source": [
-    "# Session instantiation"
+    "## Session instantiation"
    ]
   },
   {
@@ -279,7 +279,7 @@
    "id": "c6ec7b08",
    "metadata": {},
    "source": [
-    "# Experiment compilation"
+    "## Experiment compilation"
    ]
   },
   {
@@ -327,7 +327,7 @@
    "id": "edf40dd9",
    "metadata": {},
    "source": [
-    "# Experiment execution\n",
+    "## Experiment execution\n",
     "\n",
     "Returns a reference to the results object obtained by running this experiment"
    ]
@@ -353,7 +353,7 @@
    "id": "defb6204",
    "metadata": {},
    "source": [
-    "# Result Handling"
+    "## Result Handling"
    ]
   },
   {
@@ -371,7 +371,7 @@
    "id": "fcb9cf95",
    "metadata": {},
    "source": [
-    "## Get a results object\n",
+    "### Get a results object\n",
     "containing all relevant data from the last execution"
    ]
   },
@@ -451,7 +451,7 @@
    "id": "fa85988c",
    "metadata": {},
    "source": [
-    "## Compiled Experiment"
+    "### Compiled Experiment"
    ]
   },
   {
@@ -477,7 +477,7 @@
    "id": "d943cf47",
    "metadata": {},
    "source": [
-    "## Acquired Results\n",
+    "### Acquired Results\n",
     "The structure of the acquired results will change. For now, it is just adapted to the current controller implementation."
    ]
   },
@@ -502,7 +502,7 @@
    "id": "b3a15441",
    "metadata": {},
    "source": [
-    "## Convenience getters on Results object"
+    "### Convenience getters on Results object"
    ]
   },
   {
@@ -538,7 +538,7 @@
    "id": "bceaaaf3",
    "metadata": {},
    "source": [
-    "# Serialization"
+    "## Serialization"
    ]
   },
   {
@@ -683,7 +683,7 @@
    "id": "7ae9cab0",
    "metadata": {},
    "source": [
-    "# Plotting"
+    "## Plotting"
    ]
   },
   {

examples/00_reference/01_calibration_reference.ipynb

@@ -52,7 +52,7 @@
     "\n",
     "This baseline calibration can be overridden non-destructively with calibration on an `Experiment`. If a `SignalCalibration` is defined i.e. not `None` on an `ExperimentSignal`, then actual values from that `SignalCalibration` are considered while the corresponding values in the `SignalCalibration` on the `LogicalSignal` are ignored and left unmodified. If there are values in the `SignalCalibration` on the `ExperimentSignal` that are set to `None`, these values are not considered and the corresponding values in the baseline `SignalCalibration` on the corresponding `LogicalSignal` remain effective. \n",
     "\n",
-    "For example, the oscillator defined for a `LogicalSignal` can be overriden by an oscillator in the corresponding `ExperimentSignals`'s `SignalCalibration`. If this `SignalCalibration` only defines an oscillator but leaves all other values to `None`, only this oscillator will override the baseline oscillator. All values set to `None` e.g. like the mixer calibration values will leave the baseline values effective."
+    "For example, the oscillator defined for a `LogicalSignal` can be overridden by an oscillator in the corresponding `ExperimentSignals`'s `SignalCalibration`. If this `SignalCalibration` only defines an oscillator but leaves all other values to `None`, only this oscillator will override the baseline oscillator. All values set to `None` e.g. like the mixer calibration values will leave the baseline values effective."
    ]
   },
   {
@@ -175,7 +175,7 @@
    "source": [
     "## Calibrate `DeviceSetup`\n",
     "\n",
-    "Below, you'll use different methods to use calibrations, either by setting the calibration directly to the `DeviceSetup` or by ceating a `Calibration` object."
+    "Below, you'll use different methods to use calibrations, either by setting the calibration directly to the `DeviceSetup` or by creating a `Calibration` object."
    ]
   },
   {

examples/00_reference/02_experiment_definition_reference.ipynb

@@ -16,7 +16,7 @@
    "id": "5c0205b5",
    "metadata": {},
    "source": [
-    "# Imports, device setup, and example experiment\n",
+    "## Imports, device setup, and example experiment\n",
     "\n",
     "You'll start by importing LabOne Q, defining your descriptor, providing a calibration, and creating a device setup."
    ]
@@ -203,7 +203,7 @@
    "id": "9a712bcc",
    "metadata": {},
    "source": [
-    "## Example experiment\n",
+    "### Example experiment\n",
     "\n",
     "After creating your device setup, you can run an example experiment, e.g., this resonator spectroscopy."
    ]
@@ -300,7 +300,7 @@
    "id": "c6460f9b",
    "metadata": {},
    "source": [
-    "# Experiment Instantiation\n",
+    "## Experiment Instantiation\n",
     "\n",
     "You'll now create an experiment from scratch, going through each step."
    ]
@@ -419,7 +419,7 @@
    "id": "91e39f06",
    "metadata": {},
    "source": [
-    "# Sections"
+    "## Sections"
    ]
   },
   {
@@ -428,7 +428,7 @@
    "id": "7134963f",
    "metadata": {},
    "source": [
-    "## Simple Section"
+    "### Simple Section"
    ]
   },
   {
@@ -457,7 +457,7 @@
    "id": "7a33f47f",
    "metadata": {},
    "source": [
-    "## Access Current Section"
+    "### Access Current Section"
    ]
   },
   {
@@ -487,7 +487,7 @@
    "id": "7f6d8fb3",
    "metadata": {},
    "source": [
-    "## Sweep Section"
+    "### Sweep Section"
    ]
   },
   {
@@ -566,7 +566,7 @@
    "id": "8fc40e0b",
    "metadata": {},
    "source": [
-    "## Averaging Acquire Loop in near time"
+    "### Averaging Acquire Loop in near time"
    ]
   },
   {
@@ -594,7 +594,7 @@
    "id": "fd8bb93d",
    "metadata": {},
    "source": [
-    "## Averaging Acquire Loop in real time"
+    "### Averaging Acquire Loop in real time"
    ]
   },
   {
@@ -626,7 +626,7 @@
    "id": "eef26c14",
    "metadata": {},
    "source": [
-    "# Operations in near time"
+    "## Operations in near time"
    ]
   },
   {
@@ -635,7 +635,7 @@
    "id": "feeffe27",
    "metadata": {},
    "source": [
-    "## Callback Function"
+    "### Callback Function"
    ]
   },
   {
@@ -659,7 +659,7 @@
    "id": "54826045",
    "metadata": {},
    "source": [
-    "## Set node parameter in Zurich Instruments devices"
+    "### Set node parameter in Zurich Instruments devices"
    ]
   },
   {
@@ -683,7 +683,7 @@
    "id": "b05e9379",
    "metadata": {},
    "source": [
-    "# Operations in real time"
+    "## Operations in real time"
    ]
   },
   {
@@ -692,7 +692,7 @@
    "id": "0888e471",
    "metadata": {},
    "source": [
-    "## Play Pulses"
+    "### Play Pulses"
    ]
   },
   {
@@ -720,7 +720,7 @@
    "id": "bfdea064",
    "metadata": {},
    "source": [
-    "## Acquire Signals"
+    "### Acquire Signals"
    ]
   },
   {
@@ -760,7 +760,7 @@
    "id": "94b521ca",
    "metadata": {},
    "source": [
-    "## Delay"
+    "### Delay"
    ]
   },
   {
@@ -785,7 +785,7 @@
    "id": "1f40cceb",
    "metadata": {},
    "source": [
-    "## Signal Reservation"
+    "### Signal Reservation"
    ]
   },
   {

examples/00_reference/03_section_tutorial.ipynb

@@ -1071,7 +1071,7 @@
    "source": [
     "Now we'll implement a full Ramsey sequence using one drive line, a measurement line, and a acquisition line.\n",
     "\n",
-    "We'll first define some new pulses along with sweeping and averaging paramters."
+    "We'll first define some new pulses along with sweeping and averaging parameters."
    ]
   },
   {

examples/00_reference/05_pulse_inspector_plotter.ipynb

@@ -28,7 +28,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Inversion with gaussian pulse"
+    "## Inversion with gaussian pulse"
    ]
   },
   {
@@ -89,7 +89,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Inversion with flat-top Gaussian pulse"
+    "## Inversion with flat-top Gaussian pulse"
    ]
   },
   {
@@ -151,7 +151,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Inversion with DRAG pulse"
+    "## Inversion with DRAG pulse"
    ]
   },
   {