Add units flow page to docs (#689)

Author: teutoburg

docs/source/conf.py

@@ -67,6 +67,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.napoleon',
     'sphinx_copybutton',
+    'sphinxcontrib.mermaid',
     'myst_nb',
 ]
 

docs/source/faqs/scopesim_units_flow.md

@@ -0,0 +1,64 @@
+# Approximate sketch of "units flow" in ScopeSim
+
+Effects that change units are shown in hexagonal boxes.
+Rectangular boxes are basically `ImageHDU` wrappers.
+Parallelogram boxes are lists of other entities.
+
+```{mermaid}
+%%{init: {"theme": "dark"} }%%
+flowchart TB
+    Source(["`Source
+              [ph/cm2/s/AA(/arcsec2)]
+              [PHOTLAM(/arcsec2)]`"])
+    FOV1[/"`FOV.fields
+            [ph/cm2/s/AA(/arcsec2)]`"/]
+    FOV2["`FOV.hdu
+           [ph/s]`"]
+    FOV3[/"`FOV.fields
+            [ph/cm2/s/AA(/arcsec2)]`"/]
+    FOV4["`FOV.hdu
+           [ph/s/um/arcsec2]`"]
+    FOV5["`FOV.hdu
+           [ph/s]`"]
+    SPT{{"`SpectralTrace:
+           dispersion, sum(sky)`"}}
+    IMP["`ImagePlane
+          [ph/s]`"]
+    Det1["`Detector
+           [ph/s]`"]
+    QECurve{{"`QECurve:
+               ph/s -> e-/s`"}}
+    Det2["`Detector
+           [e-/s]`"]
+    SE{{"`ExposureIntegration:
+          sum(time)`"}}
+    Det3["`Detector
+           [e-]`"]
+    ADC{{"`ADConversion:
+           e- -> ADU`"}}
+    Det4["`Detector
+           [ADU]`"]
+    Output(["`Output
+              [ADU]`"])
+
+    Source-- extract -->FOV1
+    subgraph Imaging
+        FOV1-- "sum(wave), *area" -->FOV2
+    end
+    Source-- extract -->FOV3
+    subgraph Spectroscopy
+        FOV3-- *area -->FOV4
+        FOV4-->SPT
+        SPT-->FOV5
+    end
+    FOV2-- project -->IMP
+    FOV5-- project -->IMP
+    IMP-- "extract" -->Det1
+    Det1-->QECurve
+    QECurve-->Det2
+    Det2-->SE
+    SE-->Det3
+    Det3-->ADC
+    ADC-->Det4
+    Det4-->Output
+```

poetry.lock

@@ -65,6 +65,7 @@ jupyter-sphinx = ">=0.5.3"
 sphinx-copybutton = "^0.5.2"
 myst-nb = "^1.2.0"
 sphinxcontrib-apidoc = ">=0.6.0"
+sphinxcontrib-mermaid = "^1.0.0"
 nbsphinx = "^0.9.6"
 numpydoc = "^1.6.0"
 scopesim_templates = ">=0.6.0"