Merge pull request #4 from LowellObservatory/deveny_pickup

Deveny Pickup Scrubber Tool

.github/workflows/documentation.yaml

@@ -0,0 +1,27 @@
+name: Docs
+on: [push, pull_request, workflow_dispatch]
+permissions:
+    contents: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # we want to find git tags to pass version to sphinx
+          fetch-depth: 0
+      - uses: actions/setup-python@v3
+      - name: Install dependencies
+        run: |
+          pip install sphinx sphinx_rtd_theme sphinx-automodapi .[dev]
+      - name: Sphinx build
+        run: |
+          cd doc ; make clean ; make html
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: doc/_build/html
+          force_orphan: true

README.rst

@@ -1,12 +1,15 @@
 .. |License| image:: https://img.shields.io/github/license/LowellObservatory/LDTObserverTools
    :target: https://github.com/LowellObservatory/LDTObserverTools/blob/main/LICENSE
 
-.. |astropy| image:: http://img.shields.io/badge/powered%20by-AstroPy-orange.svg?style=flat
-    :target: http://www.astropy.org/
+.. |astropy| image:: https://img.shields.io/badge/powered%20by-AstroPy-orange.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
 
+.. |issues| image:: https://img.shields.io/github/issues/LowellObservatory/LDTObserverTools?style=social
+   :target: https://github.com/LowellObservatory/LDTObserverTools
+
 .. |stars| image:: https://img.shields.io/github/stars/LowellObservatory/LDTObserverTools?style=social
    :target: https://github.com/LowellObservatory/LDTObserverTools
 
@@ -30,10 +33,18 @@ LDTObserverTools |forks| |stars| |watch|
 |github| |astropy| |License|
 
 
-**Version**: |version|
+The LDTObserverTools package is a collection of command-line and GUI tools
+for observers at the Lowell Discovery Telescope (LDT) in Happy Jack, AZ.
 
-LDTObserverTools is a collection of command-line and GUI tools for observers at
-the Lowell Discovery Telescope (LDT) in Happy Jack, AZ.
+Some of these tools are Python ports of existing tools written in other
+languages, and others are newly written to meet particular needs of the
+observing community.  Detailed instructions on how to use each tool are
+contained in the `online documentation
+<https://lowellobservatory.github.io/LDTObserverTools/>`__.  Please use
+the GitHub `Issues 
+<https://github.com/LowellObservatory/LDTObserverTools/issues>`__ and/or
+`Pull Requests <https://github.com/LowellObservatory/LDTObserverTools/pulls>`__
+features to report bugs or suggest new tools and features.
 
 .. contents:: Table of Contents
     :depth: 1
@@ -51,81 +62,28 @@ List of Programs
 Tools Contained in this Package:
 --------------------------------
 
-   - ``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`]
-
-   - ``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.  Online help is available with the ``-h`` option.  [`Completed: 2021-11-19`]
-
-   - ``fix_ldt_header``: Replace / add / update FITS keyword values.  While named for
-     the LDT, it can beused with any FITS file (or list of files).  The inspiration for
-     this script is the cases when the LDT / LOUI does not input the proper information
-     in FITS headers (`e.g.`, ``GRATING = UNKNOWN`` for DeVeny before the drop-down
-     menu has been selected).  Online help is available with the ``-h`` option.
-     [`Completed: 2022-10-17`]
-
-   - ``deveny_collfocus``: Use the specified grating angle and mount temperature
-     to suggest a range for use with the DeVeny LOUI collimator Focus Sequence
-     function.  This GUI computes the expected focus from an emperical equation
-     derived from DeVeny data from 2017-2020, and then suggests the focus range.
-     This is important because, unlike all other focus routines at LDT,
-     this function takes the **starting point**, step, and number of exoposures
-     rather than the **expected focus value**, step, and number of exposures.
-     [`Completed: 2023-07-31`]
+  - DeVeny Spectrograph grating angle calculator (``deveny_grangle``)
+
+  - DeVeny Spectrograph collimator focus sequence estimator (``deveny_collfocus``)
+
+  - DeVeny Spectrograph collimator focus calculator (``dfocus``)
+
+  - DeVeny Spectrograph pickup noise scrubber (``scrub_deveny_pickup`` -- *beta testing*)
+
+  - Simple FITS header fixing tool (``fix_ldt_header``)
 
 .. _future:
 
 Future Tools (planned or in development):
 -----------------------------------------
 
-   - ``lmi_etc``: Python GUI version of the LMI exposure time calculator
-     (http://www2.lowell.edu/users/massey/LMI/etc_calc.php).
-
-   - ``neocp_ephem``: An ephemeris-generating tool for querying the JPL Scout database
-     for short-shelf- life NEOs that have not yet been assigned a Horizons identifier.
-     This tool will turn the returned data into a file that can be ingested into the
-     LDT TCS for observations.
-
-   - ``validate_input_list``: The extant input list validation tool
-     (https://confluence.lowell.edu/display/LDTOI/Validate+Input+List) was
-     produced in 2015 using an old Java Runtime Environment that is not available on
-     most modern operating systems.  As such, the tool is virtually useless.  This
-     python program would provide this key functionality in a modern environment.
-
-   - ``observer_target_list``: The extant observer target list tool
-     (https://confluence.lowell.edu/display/LDTOI/Observer+Target+List+User+Manual)
-     was produced in 2015 using an old Java Runtime Environment that is not available on
-     most modern operating systems.  It still runs happily on the LDT observer machines,
-     but those will need to be replaced at some point.  This python version will provide
-     a future-proof solution.
-
-   - ``scrub_deveny_pickup``: The DeVeny spectrograph suffers from EM ground-loop
-     pickup noise in the readout electronics.  While the Instrument Groups is working
-     diligently to identify the source of this noise, it is still affecting frames at
-     the 5-10 DN level.  This routine will attempt to clean the pattern from the raw
-     frames.  It works in an iterative fashion with the spectroscopic data reduciton
-     pipeline `PypeIt <https://pypeit.readthedocs.io/en/release/index.html>`_ to
-     identify and extract sources and sky signal before attempting to fit and remove
-     the remaining pickup noise.  If you wish to use this routine, please follow the
-     instructions in :ref:`optional-dependencies` to include PypeIt in your
-     LDTObserverTools installation.
+  - LMI exposure time calculator (``lmi_etc``)
+
+  - NEO Confirmation Page ephemeris generator (``neocp_ephem``)
+
+  - Input List Validator (``validate_input_list``)
+
+  - Observer Target List Tool (``observer_target_list``)
 
 ==================
 
@@ -139,10 +97,11 @@ Installing
 Set up a clean python environment
 ---------------------------------
 
-Because installing a python tool like LDTObserverTools also installs or upgrades
-its :ref:`dependencies`, the best course of action is to set up a clean python
-environment into which the installation will occur.  This mitigates any possible
-dependency conflicts with other packages you use.
+Because installing a python tool like LDTObserverTools also installs or
+upgrades its :ref:`Package Dependencies <dependencies>`, the best course of
+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``:
 
@@ -163,7 +122,7 @@ Installing LDTObserverTools via ``pip``
 .. note::
   The commands here assume ``pip`` is associated with Python3.  To check, run
   ``pip --version`` from the command line and check that the associated python
-  version is ``>= 3.9``.
+  version is ``>= 3.10``.
 
   Also, you will need ``git`` installed on your system / in your environment.
 
@@ -191,14 +150,16 @@ simply be a matter of executing:
 Optional Dependencies
 ^^^^^^^^^^^^^^^^^^^^^
 
-Some of the instrument-specific routines in this package require additional dependencies
-that are not otherwise needed by the majority of the routines herein.
+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.
 
-   - 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 ``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.`:
 
-      .. 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/Makefile

@@ -37,16 +37,8 @@ clean:
 
 apirst:
 	SPHINX_APIDOC_OPTIONS=$(SPHINXAPIOPT) $(SPHINXAPI) --separate -o ./api ../obstools ../obstools/version.py
-# python3 ./scripts/build_dependency_rst.py
-# python3 ./scripts/build_detector_table.py
-# python3 ./scripts/build_imgproc_defaults.py
-# python3 ./scripts/build_par_rst.py
-# python3 ./scripts/build_specobj_rst.py
-# python3 ./scripts/build_calib_images_rst.py
-# python3 ./scripts/write_script_help.py
-# python3 ./scripts/build_bitmask_rst.py
-# python3 ./scripts/build_spectbl_rst.py
-# python3 ./scripts/make_example_files.py
+	python ./scripts/write_script_help.py
+	python ./scripts/build_dependency_rst.py
 
 html:
 	make apirst

doc/api/obstools.fix_ldt_header.rst

@@ -0,0 +1,8 @@
+obstools.fix\_ldt\_header module
+================================
+
+.. automodule:: obstools.fix_ldt_header
+   :members:
+   :private-members:
+   :undoc-members:
+   :show-inheritance:

doc/api/obstools.rst

@@ -13,7 +13,7 @@ Submodules
    obstools.deveny_grangle
    obstools.dfocus
    obstools.etc_calc
-   obstools.fits_utils
+   obstools.fix_ldt_header
    obstools.neocp_ephem
    obstools.scrub_deveny_pickup
    obstools.utils

doc/conf.py

@@ -10,18 +10,13 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os
-import sys
-
-sys.path.insert(0, os.path.abspath("."))
-from pkg_resources import get_distribution
-
-# Get configuration information from setup.cfg
 from configparser import ConfigParser
+from importlib import metadata
+import pathlib
 
+# Get configuration information from setup.cfg
 conf = ConfigParser()
-
-conf.read([os.path.join(os.path.dirname(__file__), "..", "setup.cfg")])
+conf.read([pathlib.Path(__file__).parents[1] / "setup.cfg"])
 setup_cfg = dict(conf.items("metadata"))
 
 # -- Project information -----------------------------------------------------
@@ -52,7 +47,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
-    "sphinx.ext.autosectionlabel",
+    # "sphinx.ext.autosectionlabel",
 ]
 
 # automodapi
@@ -70,9 +65,10 @@
 napoleon_use_rtype = False
 
 # Autosection
-
 autosectionlabel_prefix_document = True
 
+# Figures
+numfig = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -109,9 +105,7 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {
-    "logo_only": True,
-}
+html_theme_options = {"logo_only": True, "prev_next_buttons_location": None}
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
@@ -126,7 +120,7 @@
 master_doc = "index"
 
 # The full version, including alpha/beta/rc tags.
-version = get_distribution(setup_cfg["name"]).version
+version = metadata.version(setup_cfg["name"])
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
@@ -136,5 +130,6 @@
     "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)
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "pypeit": ("https://pypeit.readthedocs.io/en/release/", None),
 }