More docs!

	modified:   .github/workflows/documentation.yaml
	modified:   README.rst
	modified:   doc/conf.py
	modified:   doc/deveny_collfocus.rst
	modified:   doc/deveny_grangle.rst
	modified:   doc/dfocus.rst
	new file:   doc/figures/pyfocus.page1_example.pdf
	new file:   doc/figures/pyfocus.page1_example.png
	new file:   doc/figures/pyfocus.page1_example.svg
	new file:   doc/figures/pyfocus.page2_example.pdf
	new file:   doc/figures/pyfocus.page2_example.png
	new file:   doc/figures/pyfocus.page2_example.svg
	new file:   doc/figures/pyfocus.page3_example.pdf
	new file:   doc/figures/pyfocus.page3_example.png
	new file:   doc/figures/pyfocus.page3_example.svg
	modified:   doc/fix_ldt_header.rst
	modified:   doc/help/dfocus.rst
	modified:   doc/include/dependencies_table.rst
	modified:   doc/scrub_deveny_pickup.rst
	modified:   obstools/deveny_collfocus.py
	modified:   obstools/deveny_grangle.py
	modified:   obstools/dfocus.py
	modified:   obstools/fix_ldt_header.py
	modified:   obstools/lmi_etc.py
	modified:   obstools/neocp_ephem.py
	modified:   setup.cfg

.github/workflows/documentation.yaml

@@ -10,7 +10,9 @@ jobs:
         with:
           # we want to find git tags to pass version to sphinx
           fetch-depth: 0
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
       - name: Install dependencies
         run: |
           pip install sphinx sphinx_rtd_theme sphinx-automodapi .[dev]

README.rst

@@ -1,24 +1,30 @@
 .. |License| image:: https://img.shields.io/github/license/LowellObservatory/LDTObserverTools
    :target: https://github.com/LowellObservatory/LDTObserverTools/blob/main/LICENSE
 
-.. |astropy| image:: https://img.shields.io/badge/powered%20by-AstroPy-orange.svg?style=flat
+.. |astropy| image:: https://img.shields.io/badge/powered%20by-AstroPy-blue.svg?style=flat
     :target: https://www.astropy.org/
 
 .. |forks| image:: https://img.shields.io/github/forks/LowellObservatory/LDTObserverTools?style=social
-   :target: https://github.com/LowellObservatory/LDTObserverTools
+   :target: https://github.com/LowellObservatory/LDTObserverTools/forks
 
-.. |issues| image:: https://img.shields.io/github/issues/LowellObservatory/LDTObserverTools?style=social
-   :target: https://github.com/LowellObservatory/LDTObserverTools
+.. |issues| image:: https://img.shields.io/github/issues/LowellObservatory/LDTObserverTools?style=badge
+   :target: https://github.com/LowellObservatory/LDTObserverTools/issues
+
+.. |pulls| image:: https://img.shields.io/github/issues-pr/LowellObservatory/LDTObserverTools?style=badge
+   :target: https://github.com/LowellObservatory/LDTObserverTools/pulls
 
 .. |stars| image:: https://img.shields.io/github/stars/LowellObservatory/LDTObserverTools?style=social
-   :target: https://github.com/LowellObservatory/LDTObserverTools
+   :target: https://github.com/LowellObservatory/LDTObserverTools/stargazers
 
 .. |watch| image:: https://img.shields.io/github/watchers/LowellObservatory/LDTObserverTools?style=social
-   :target: https://github.com/LowellObservatory/LDTObserverTools
+   :target: https://github.com/LowellObservatory/LDTObserverTools/watchers
 
 .. |github| image:: https://img.shields.io/badge/GitHub-LDTObserverTools-brightgreen
    :target: https://github.com/LowellObservatory/LDTObserverTools
 
+.. |language| image:: https://img.shields.io/github/languages/top/LowellObservatory/LDTObserverTools
+   :target: https://github.com/LowellObservatory/LDTObserverTools
+
 .. image:: https://raw.githubusercontent.com/LowellObservatory/LDTObserverTools/main/doc/_static/obstools_logo.png
     :target: https://github.com/LowellObservatory/LDTObserverTools
     :width: 500
@@ -32,6 +38,7 @@ LDTObserverTools |forks| |stars| |watch|
 
 |github| |astropy| |License|
 
+|language| |issues| |pulls|
 
 The LDTObserverTools package is a collection of command-line and GUI tools
 for observers at the Lowell Discovery Telescope (LDT) in Happy Jack, AZ.

doc/conf.py

@@ -125,11 +125,13 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    "astropy": ("https://docs.astropy.org/en/stable/", None),
     "attrs": ("https://www.attrs.org/en/stable/", None),
+    "astropy": ("https://docs.astropy.org/en/stable/", None),
+    "ccdproc": ("https://ccdproc.readthedocs.io/en/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "pypeit": ("https://pypeit.readthedocs.io/en/release/", None),
+    "stomp": ("https://jasonrbriggs.github.io/stomp.py/", None)
 }

doc/deveny_collfocus.rst

@@ -53,10 +53,15 @@ The script usage can be displayed by calling the script with the
 
 .. include:: help/deveny_collfocus.rst
 
-When the application launches, a GUI window will appear:
+When the application launches, a GUI window will appear as in
+:numref:`collfocus_startup`.
 
-.. image:: figures/deveny_collfocus_startup.png
+.. _collfocus_startup:
+.. figure:: figures/deveny_collfocus_startup.png
     :class: with-shadow
+    :alt: GUI at startup
+
+    -- The ``deveny_collfocus`` GUI at startup.
 
 
 If the application is launched from one of the observer computers at LDT
@@ -74,10 +79,16 @@ windows.  You will always need to select the rear filter setting you are using.
 
 When you click "Compute", the bottom half of the GUI is populated with the
 estimated focus value from the equation above and values to enter into the
-DeVeny LOUI focus sequence tab.
+DeVeny LOUI focus sequence tab.  See :numref:`collfocus_values`.
 
-.. image:: figures/deveny_collfocus_values.png
+.. _collfocus_values:
+.. figure:: figures/deveny_collfocus_values.png
     :class: with-shadow
+    :alt: GUI after clicking "Compute"
+
+    -- The ``deveny_collfocus`` GUI after clicking "Compute".  The estimated
+    focus value (with uncertainty) is printed, along with suggested values for
+    use with the LOUI Focus Sequence tab.
 
 Observers should note that the lower limit on the collimator focus motorized
 stage is 7.75 mm.  In warm weather and/or for large grating tilt angles, the

doc/deveny_grangle.rst

@@ -59,19 +59,30 @@ The script usage can be displayed by calling the script with the
 
 .. include:: help/deveny_grangle.rst
 
-In its default mode, the tool launches a GUI window:
+In its default mode, the tool launches a GUI window as in
+:numref:`grangle_startup`.
 
-.. image:: figures/deveny_grangle_startup.png
+.. _grangle_startup:
+.. figure:: figures/deveny_grangle_startup.png
     :class: with-shadow
+    :alt: GUI at startup
+
+    -- The ``deveny_collfocus`` GUI at startup.
 
 Select your grating from the dropdown menu (this selects the groove density),
 and enter your desired central wavelength (in angstroms).  When you click
 "Compute", the bottom half of the GUI is populated with the needed grating tilt
 value from the equation above and the computed slit demagnification value (see
-the DeVeny user manual for a brief discussion of grating physics):
+the DeVeny user manual for a brief discussion of grating physics).  See
+:numref:`grangle_values`.
 
-.. image:: figures/deveny_grangle_values.png
+.. _grangle_values:
+.. figure:: figures/deveny_grangle_values.png
     :class: with-shadow
+    :alt: GUI after clicking "Compute"
+
+    -- The ``deveny_grangle`` GUI after clicking "Compute".  The needed grating
+    tilt angle and computed slit demagnification values have been populated.
 
 There are two optional modes for running this tool:
 

doc/dfocus.rst

@@ -14,20 +14,92 @@ Status: Completed 2021-11-19
 Overview
 ========
 
-   - ``dfocus``: Compute the needed collimator focus based on a series of arc line
-     frames taken at various collimator settings.  Read in the arc lamp frames in
-     the current night's focus directory, find the appropriate spectral lines in each
-     frame, compute the FHWM (or other measure) of those lines, plot the FHWM as a
-     function of collimator position and suggest the optimal focus position.  This
-     program is executed identically to the old IDL version.  The python version
-     uses :obj:`scipy.signal` processing routines for identifying line peaks and widths,
-     resulting in more accurate and consistent estimates of the correct collimator
-     focus position.  Rather than separately producing plots to the screen and disk,
-     this version writes all plots to a PDF, then launches ``Preview.app`` to display
-     the plots on the screen.  Newly added is a readout of the mount temperature so
-     the user can determine when/if the collimator needs to be refocused during the
-     night.
+The internal optics of the DeVeny Spectrograph are focused by pistoning the
+collimator mirror (a separate task from focusing the telescope onto the
+spectrograph).  The DeVeny LOUI includes a tab for performing a focus sequence
+(images of arc lines interleaved with collimator focus moves).  The
+:ref:`deveny_collfocus` tool is used to estimate the focus value and sequence
+range needed.
 
+Once the sequence of focus images has been collected, this tool will analyze
+the arc lines in each frame to calculate the optimal position at which you
+should set the collimator.  See :ref:`dfocus_usage` for details of the
+command-line options for use with the tool.  When run, the following processing
+steps are applied to the focus frames:
+
+    #. All frames are read in, and the middle frame is inspected to find
+       appropriate spectral lines for analysis.  (This frame is what is shown
+       in :numref:`pyfocus_p1`, theoretically the frame closest to focus,
+       especially if ``deveny_collfocus`` was used to generate the sequence
+       range.)
+    #. The marked lines are then identified in all the other frames, and the
+       FWHM for each is computed using :obj:`scipy.signal` processing routines.
+    #. The FWHM as a function of collimator position is computed for each line
+       identified, and a parabola is fit to the plot (see
+       :numref:`pyfocus_p3`).
+    #. For arc each line, the minimum (red lines in :numref:`pyfocus_p3`) and
+       optimal (blue lines) focus values are computed.  See the DeVeny manual
+       for a discussion of astigmatism and why the two values are not the same.
+    #. Finally, the optimal focus value is plotted as a function of CCD column
+       position (:numref:`pyfocus_p2`) to find the overall optimal collimator
+       focus value to use.
+
+An example terminal output corresponding to the figures is shown below:
+
+    .. code-block:: console
+
+        ================================================================================
+          DeVeny Collimator Focus Calculator
+
+         Processing center focus image /deveny/20210520a/20210520.0177.fits...
+          Background level: 2351.1   Detection threshold level: 2451.1
+         Number of lines found: 39
+
+         Processing arc images...
+        100%|████████████████████████████████████████| 10/10 [00:00<00:00, 40.87frame/s]
+
+          Median value of all linewidths: 3.03 pix
+        ================================================================================
+        *** Recommended (Median) Optimal Focus Position: 10.49 mm
+        *** Note: Current Mount Temperature is: 18.0ºC
+
+          Plots have been saved to: pyfocus.20210520.040659.pdf
+
+In both the terminal output and the plots, the current mount temperature is
+noted so that the observer can judge if the collimator focus needs to be
+revisited during the night based on temperature changes.  The collimator focus
+temperature term is approximately :math:`-0.08~{\rm mm/C^{\circ}}`, meaning that
+a temperature *decrease* of :math:`5 {\rm~C^{\circ}}` will cause a
+:math:`0.4~{\rm mm}` *increase* in the optimal collimator focus position.
+
+
+.. _pyfocus_p1:
+.. figure:: figures/pyfocus.page1_example.*
+    :class: with-shadow
+    :alt: Arc line plot
+
+    -- Example of page 1 of the output PDF, arc line identification plot.
+
+
+.. _pyfocus_p2:
+.. figure:: figures/pyfocus.page2_example.*
+    :class: with-shadow
+    :alt: Optimal focus versus line position
+
+    -- Example of page 2 of the output PDF, optimal focus versus line position plot.
+
+
+.. _pyfocus_p3:
+.. figure:: figures/pyfocus.page3_example.*
+    :class: with-shadow
+    :alt: Individual line focus curves
+
+    -- Example of page 3 of the output PDF, individual line focus curves.
+
+
+
+
+.. _dfocus_usage:
 
 Usage
 =====
@@ -36,4 +108,28 @@ The script usage can be displayed by calling the script with the
 ``-h`` option:
 
 .. include:: help/dfocus.rst
-
+
+This command-line tool must be invoked from the ``/deveny/<UTDATE>/focus``
+directory on the observer machine (``dct-obs1`` / ``dct-obs2``) so that it can
+find the focus index files created by the DeVeny LOUI.  To run the tool on the
+most recent focus sequence taken, simply run the routine with no options.
+
+If more than one focus sequence was taken, the tool can analyze a particular
+sequence by using the ``--flog`` optional input, where the file log has the
+form ``deveny_focus.<UTDATE>.<UTTIME>``.  For instance, to produce the plots in
+:numref:`pyfocus_p1` - :numref:`pyfocus_p3`, you would:
+
+    .. code-block:: console
+
+        $ cd /deveny/20210520/focus
+        $ dfocus --flog deveny_focus.20210520.040659
+
+If you want to increase the threshold for detected lines above the default
+100 |nbsp| DN over background (to decrease the number of lines detected), use
+the ``--thresh`` optional input.
+
+By default, the tool tries to launch Apple's Preview App (the observer machines
+at LDT are iMacs) to display the plots shown in :numref:`pyfocus_p1` -
+:numref:`pyfocus_p3`.  If running on macOS, and you desire to **not** display
+the plots, use the ``--nodisplay`` option.  If this tool is being run on a
+different operating system, it will simply bypass this step.