From adefe10ca4a831a570bcc0f969d784bc42b83a24 Mon Sep 17 00:00:00 2001
From: Tammo Jan Dijkema <dijkema@astron.nl>
Date: Tue, 19 Mar 2024 12:43:57 +0000
Subject: [PATCH] Update demixer documentation

---
 docs/schemas/Demixer.yml                        | 17 ++++++++++-------
 ...ription of baseline selection parameters.yml |  4 ++--
 docs/schemas/SmartDemixer.yml                   |  6 +++---
 3 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/docs/schemas/Demixer.yml b/docs/schemas/Demixer.yml
index 246cd405c..8a89f879c 100644
--- a/docs/schemas/Demixer.yml
+++ b/docs/schemas/Demixer.yml
@@ -1,5 +1,8 @@
 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
diff --git a/docs/schemas/Description of baseline selection parameters.yml b/docs/schemas/Description of baseline selection parameters.yml
index 2f8356059..f0e37e610 100644
--- a/docs/schemas/Description of baseline selection parameters.yml	
+++ b/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?
diff --git a/docs/schemas/SmartDemixer.yml b/docs/schemas/SmartDemixer.yml
index 27cb16173..a1c5da5e1 100644
--- a/docs/schemas/SmartDemixer.yml
+++ b/docs/schemas/SmartDemixer.yml
@@ -1,5 +1,5 @@
 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&#46;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
-- 
GitLab