Merge pull request #6 from LowellObservatory/doc_bug_fixes

Flesh out the documentation and fix bugs

.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.
@@ -103,7 +110,7 @@ action is to setup a clean python environment into which the installation will
 occur.  This mitigates any possible dependency conflicts with other packages
 you use.
 
-The recommended method of setting up a new envrionment is with ``conda``:
+The recommended method of setting up a new environment is with ``conda``:
 
 .. code-block:: console
 
@@ -150,16 +157,16 @@ simply be a matter of executing:
 Optional Dependencies
 ^^^^^^^^^^^^^^^^^^^^^
 
-There are no optional dependencies at this time.
+.. There are no optional dependencies at this time.
 
-.. Some of the instrument-specific routines in this package require additional dependencies
-.. that are not otherwise needed by the majority of the routines herein.
+Some of the instrument-specific routines in this package require additional dependencies
+that are not otherwise needed by the majority of the routines herein.
 
-..    - If you are using the ``deveny_pickup_cleaner`` routine, you will need the
-..      spectroscopic data reduction pipeline PypeIt for the iterative cleaning of
-..      the pickup noise.  It can be installed by including it in the optional
-..      dependencies, `e.g.`:
+   - If you are using the ``scrub_deveny_pickup`` tool, you will need the
+     spectroscopic data reduction pipeline `PypeIt <https://pypeit.readthedocs.io/en/release/>`_
+     for the iterative cleaning of the pickup noise.  It can be installed by
+     including it in the optional dependencies, *e.g.*:
 
-..       .. code-block:: console
+      .. code-block:: console
 
-..         pip install "obstools[pypeit] @ git+https://github.com/LowellObservatory/LDTObserverTools"
+        pip install "obstools[pypeit] @ git+https://github.com/LowellObservatory/LDTObserverTools"

doc/api/obstools.lmi_etc.rst

@@ -0,0 +1,8 @@
+obstools.lmi\_etc module
+========================
+
+.. automodule:: obstools.lmi_etc
+   :members:
+   :private-members:
+   :undoc-members:
+   :show-inheritance:

doc/api/obstools.rst

@@ -12,8 +12,8 @@ Submodules
    obstools.deveny_collfocus
    obstools.deveny_grangle
    obstools.dfocus
-   obstools.etc_calc
    obstools.fix_ldt_header
+   obstools.lmi_etc
    obstools.neocp_ephem
    obstools.scrub_deveny_pickup
    obstools.utils

doc/conf.py

@@ -47,6 +47,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
+    "sphinx_subfigure",
     # "sphinx.ext.autosectionlabel",
 ]
 
@@ -125,11 +126,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

@@ -1,3 +1,10 @@
+.. include:: include/links.rst
+
+.. |nbsp| unicode:: 0xA0 
+   :trim:
+
+.. _deveny_collfocus:
+
 =================================
 DeVeny Collimator Focus Estimator
 =================================
@@ -26,7 +33,8 @@ yield the approximate relationship:
     \end{aligned}
 
 where :math:`T_{\rm m}` is the mount temperature and tilt is the grating tilt
-angle.  This equation is coded into the GUI tool.
+angle.  The RMS of the fit is :math:`\sim 0.6` |nbsp| mm.  This equation is coded into
+the GUI tool.
 
 Unlike other focus procedures at LDT, the DeVeny LOUI focus sequence script
 does not take the *expected* focus value, but rather one end of the range,
@@ -45,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
@@ -66,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

@@ -1,3 +1,10 @@
+.. include:: include/links.rst
+
+.. |nbsp| unicode:: 0xA0 
+   :trim:
+
+.. _deveny_grangle:
+
 ===============================
 DeVeny Grating Angle Calculator
 ===============================
@@ -7,14 +14,41 @@ Status: Completed 2021-01-26
 Overview
 ========
 
-   - ``deveny_grangle``: Compute the desired grating angle based on selected
-     grating and desired central wavelength.  This routine comes with two interfaces.
-     The default GUI features a dropdown menu for grating selection and contains error
-     checking on the input for central wavelength.  There is a ``MAX_GUI`` option for
-     computing central wavelength given the grating angle in addition to the standard
-     GUI features.  Also included is a command-line interface, identical to the old
-     IDL function.  Online help is available with the ``-h`` option.
-     [`Completed: 2021-01-26`]
+.. _grateq:
+
+The Grating Equation
+^^^^^^^^^^^^^^^^^^^^
+
+The angles at which the diffracted light reflects off the grating are given
+by the grating equation:
+
+.. math::
+
+    \begin{equation}
+    m\lambda = d(\sin \theta _{i}-\sin \theta _{m})~,
+    \end{equation}
+
+where :math:`d` is the spacing between adjacent grooves on the grating,
+:math:`\theta_{i} = \theta_{\rm grangle} + 10^{\circ}` is the incident angle,
+and :math:`\theta_{m} = 55^{\circ} - \theta_{i}` is the outgoing angle for light
+with wavelength :math:`\lambda` diffracting into order :math:`m` (see the
+DeVeny user manual for a description of the physical layout of the
+spectrograph).  The DeVeny gratings are typically operated in
+1\ :superscript:`st`\  order (:math:`m = 1`), although use of :math:`m=2` would
+possible with the proper short-pass order-blocking filters to remove
+1\ :superscript:`st`\ -order light.
+
+This tool computes the necessary tilt :math:`\theta_{\rm grangle}` by
+numerically solving the equation below for a given grating.  The computation
+uses the groove density (in g/mm) in place of :math:`d`, and finds
+:math:`\theta_{\rm grangle}` for a specified 1\ :superscript:`st`\ -order
+central wavelength (:math:`\lambda_c`) in Angstroms on the spectral CCD.
+
+.. math::
+
+    \begin{equation}
+    \lambda_c~({\rm \mathring{A}}) = \frac{\sin(\theta_{\rm grangle} +10^{\circ}) - \sin(45^{\circ} - \theta_{\rm grangle})}{ {\rm groove~density~(g/mm)} }\times 10^7
+    \end{equation}
 
 
 Usage
@@ -24,3 +58,37 @@ The script usage can be displayed by calling the script with the
 ``-h`` option:
 
 .. include:: help/deveny_grangle.rst
+
+In its default mode, the tool launches a GUI window as in
+:numref:`grangle_startup`.
+
+.. _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).  See
+:numref:`grangle_values`.
+
+.. _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:
+
+    * ``--cli``: A command-line version of this tool, which looks and functions
+      identical to the old IDL routine with the same name.
+
+    * ``--max``: The GUI will have the option to compute the central wavelength
+      from :math:`\theta_{\rm grangle}` in addition to the forward calculation
+      done in the default mode.