Update demixer documentation

docs/schemas/Demixer.yml

 description: >-
-  Demix in the old way.
+  Demix bright sources, i.e. calibrate in the direction of the birght sources and
+  subtract the bright sources from the data. Note that the calibration solution
+  is assumed to be constant over the entire frequency range, so this will only
+  work on relatively small bandwidth (e.g. a single sub-band).
 inputs:
   step_name:
     type: string
@@ -12,16 +15,16 @@ inputs:
   baseline:
     default: "\"\""
     type: string
-    doc: Baselines to demix. See Description of baseline selection parameters `.`
+    doc: Baselines to demix. See :ref:`Description of baseline selection parameters`
   blrange:
     default: []
     type: double[]
-    doc: Baselines to demix. See Description of baseline selection parameters `.`
+    doc: Baselines to demix. See :ref:`Description of baseline selection parameters`
   corrtype:
     default: cross
     type: string
     doc: >-
-      Baselines to demix. Correlation type to match? Must be auto, cross, or an
+      Baselines to demix. Correlation type to match? Must be ``auto``, ``cross``, or an
       empty string `.`
   timestep:
     default: 1
@@ -49,7 +52,7 @@ inputs:
     type: float
     doc: >-
       Time resolution to use when demixing, in seconds. If this is given, and is greater than
-      zero, it overrides `<step>.demixtimestep` `.`
+      zero, it overrides ``<step>.demixtimestep`` `.`
   demixfreqstep:
     default: 0
     type: int
@@ -74,7 +77,7 @@ inputs:
   skymodel:
     default: sky
     type: string
-    doc: Sourcedb (created with `makesourcedb`) with the sky model to calibrate on `.` When the path ends with ``.skymodel`` or ``.txt`` DP3 expects a skymodel file as used by makesourcedb. This makes it possible to directly use a skymodel file without using makesourcedb to convert the file.
+    doc: Sourcedb (created with ``makesourcedb``) with the sky model to calibrate on. When the path ends with ``.skymodel`` or ``.txt`` DP3 expects a skymodel file as used by makesourcedb. This makes it possible to directly use a skymodel file without using makesourcedb to convert the file.
   instrumentmodel:
     default: instrument
     type: string
@@ -99,7 +102,7 @@ inputs:
     default: "\"\""
     type: string
     doc: >-
-      It can be used to specify the name of the source model of the target. If
+      This setting can be used to specify the name of the source model of the target. If
       given, the target source model (its patch in the SourceDB) is taken into
       account when solving; in this case parameter ``othersources`` cannot be given.
       It cannot be given if ``ignoretarget=true``. If not given, the target is

docs/schemas/Description of baseline selection parameters.yml

@@ -72,11 +72,11 @@ inputs:
   corrtype:
     default: "\"\""
     type: string
-    doc: Correlation type to match? Must be auto, cross, or an empty string (= all) `.`
+    doc: Correlation type to match? Must be ``auto``, ``cross``, or an empty string (= all) `.`
   blrange:
     default: "[]"
     type: double?
-    doc: Zero or more ranges of physical baseline lengths (in m). A baseline matches if its length is within one of the ranges. E.g., ``blrange=[0,10000, 100000, 1e30]`` `.`
+    doc: Zero or more ranges of physical baseline lengths (in m). A baseline matches if its length is within one of the ranges. E.g., ``blrange=[0,10000, 100000, 1e30]`` matches baselines shorter than 10km and baselines longer than 100km `.`
   baseline:
     default: "\"\""
     type: baseline?

docs/schemas/SmartDemixer.yml

 description: >-
-  Demix in a new, smarter way.
+  Alternative variant of demixing, where not all the sources are demixed during the whole observation.
 inputs:
   type:
     type: string
@@ -19,7 +19,7 @@ inputs:
     default: cross
     type: string
     doc: >-
-      Baselines to demix. Correlation type to match? Must be auto, cross, or an empty string `.`
+      Baselines to demix. Correlation type to match? Must be ``auto``, ``cross``, or an empty string `.`
   target.baseline:
     default: "CS*&"
     type: string
@@ -34,7 +34,7 @@ inputs:
     default: cross
     type: string
     doc: >-
-      Baselines to use in prediction of median target amplitude. Correlation type to match? Must be auto, cross, or an empty string `.`
+      Baselines to use in prediction of median target amplitude. Correlation type to match? Must be ``auto``, ``cross``, or an empty string `.`
   timestep:
     default: 1
     type: integer