DOC: Complete API for msaflagopen (#10515)

Author: pllim

docs/jwst/msaflagopen/api_ref.rst

@@ -0,0 +1,15 @@
+===
+API
+===
+
+Public Step API
+===============
+
+.. automodapi:: jwst.msaflagopen.msaflagopen_step
+   :no-inheritance-diagram:
+
+Complete Developer API
+======================
+
+.. automodapi:: jwst.msaflagopen.msaflag_open
+   :no-inheritance-diagram:

docs/jwst/msaflagopen/arguments.rst

@@ -1,7 +1,7 @@
 Description
 ===========
 
-:Class: `jwst.msaflagopen.MSAFlagOpenStep`
+:Class: `jwst.msaflagopen.msaflagopen_step.MSAFlagOpenStep`
 :Alias: msa_flagging
 
 Overview
@@ -15,15 +15,20 @@ The correction is applicable to NIRSpec IFU and MSA exposure types.
 
 Algorithm
 ---------
-The set of shutters whose state is not commandable (i.e. they are permanently stuck
+The set of shutters whose state is not commandable (i.e., they are permanently stuck
 in 'open' or 'closed' positions) is recorded in the MSAOPER reference file.
 The reference file is searched for all shutters with any of the quantities
-'Internal state', 'TA state' or 'state' set to 'open'.
+'Internal state', 'TA state', or 'state' set to 'open'.
 
 The step loops over the list of stuck open shutters.  For each shutter, the bounding box
 that encloses the projection of the shutter onto the detector array is calculated,
 and for each pixel in the bounding box, the WCS is calculated.  If the pixel is inside
 the region affected by light through the shutter, the WCS will have valid values,
 whereas if the pixel is outside, the WCS values will be NaN.  The indices of each non-NaN
 pixel in the WCS are used to alter the corresponding pixels in the DQ array by OR'ing
-their DQ value with that for "MSA_FAILED_OPEN."
+their DQ value with that for "MSA_FAILED_OPEN".
+
+Step Arguments
+--------------
+
+The ``msaflagopen`` step has no step-specific arguments.

docs/jwst/msaflagopen/description.rst

@@ -8,7 +8,5 @@ MSAFlagOpen Correction
    :maxdepth: 2
 
    description.rst
-   arguments.rst
    reference_files.rst
-
-.. automodapi:: jwst.msaflagopen
+   api_ref.rst

docs/jwst/msaflagopen/index.rst

@@ -20,33 +20,53 @@ the following keywords are *required* in MSAOPER reference files,
 because they are used as CRDS selectors
 (see :ref:`msaoper_selectors`):
 
-=========  ==============================
+=========  ========================
 Keyword    Data Model Name
-=========  ==============================
+=========  ========================
 EXP_TYPE   model.meta.exposure.type
-=========  ==============================
+=========  ========================
 
 Reference File Format
 +++++++++++++++++++++
-The MSAOPER reference files are json format.
-
+The MSAOPER reference files are in JSON format.
 The fields are:
 
-:title: Short description of the reference file
-:reftype: Should be "MSAOPER"
-:pedigree: Should be one of "DUMMY", "GROUND" or "INFLIGHT"
-:author: Creator of the file
-:instrument: JWST Instrument; should be "NIRSPEC"
-:exp_type: EXP_TYPEs this file should be used with; should be "NRS_IFU|NRS_MSASPEC"
-:telescope: Should be "JWST"
-:useafter: Exposure datetime after which this file is applicable
-:descrip: Description of reference file
-:msaoper:
-    :Q: Quadrant; should be an integer 1-4
-    :x: x location of shutter (integer, 1-indexed)
-    :y: y location of shutter (integer, 1-indexed)
-    :state: state of shutter; should be "closed" or "open"
-    :TA state: TA state of shutter; should be "closed" or "open"
-    :Internal state: Internal state of shutter; should be "closed", "normal" or "open"
-    :Vignetted: Is the shutter vignetted?  Should be "yes" or "no"
-:history: Description of the history relevant to this file; might point to documentation
+``title``
+  Short description of the reference file
+
+``reftype``
+  Should be "MSAOPER"
+
+``pedigree``
+  Should be one of "DUMMY", "GROUND", or "INFLIGHT"
+
+``author``
+  Creator of the file
+
+``instrument``
+  JWST Instrument; should be "NIRSPEC"
+
+``exp_type``
+  EXP_TYPEs this file should be used with; should be "NRS_IFU|NRS_MSASPEC"
+
+``telescope``
+  Should be "JWST"
+
+``useafter``
+  Exposure datetime after which this file is applicable
+
+``descrip``
+  Description of reference file
+
+``msaoper``
+  - ``Q``: Quadrant; should be an integer 1-4
+  - ``x``: x location of shutter (integer, 1-indexed)
+  - ``y``: y location of shutter (integer, 1-indexed)
+  - ``state``: state of shutter; should be "closed" or "open"
+  - ``TA state``: TA state of shutter; should be "closed" or "open"
+  - ``Internal state``: Internal state of shutter; should be "closed", "normal" or "open"
+  - ``Vignetted``: Is the shutter vignetted?  Should be "yes" or "no"
+
+``history``
+  Description of the history relevant to this file;
+  might point to documentation

docs/jwst/references_general/msaoper_reffile.inc

@@ -7,8 +7,7 @@ MSAOPER is not applicable for instruments not in the table.
 All keywords used for file selection are *required*.
 
 ========== ======================================
-Instrument Keywords                               
+Instrument Keywords
 ========== ======================================
-NIRSpec    INSTRUME, EXP_TYPE, DATE-OBS, TIME-OBS 
+NIRSpec    INSTRUME, EXP_TYPE, DATE-OBS, TIME-OBS
 ========== ======================================
-

docs/jwst/references_general/msaoper_selection.inc

@@ -44,11 +44,11 @@ def do_correction(input_model, shutter_refname, wcs_refnames):
     Parameters
     ----------
     input_model : `~stdatamodels.jwst.datamodels.ImageModel`
-        Science data to be corrected. Updated in place.
+        Science data to be corrected. Updated in-place.
     shutter_refname : str
         Name of MSAOPER reference file.
     wcs_refnames : dict
-        Dictionary of wcs reference file names.
+        Dictionary of WCS reference file names.
 
     Returns
     -------
@@ -78,21 +78,21 @@ def flag(input_datamodel, failed_slitlets, wcs_refnames):
     that for the MSA_FAILED_OPEN standard flag.  All other science data
     arrays are unchanged.
 
-    The input datamodel is modified in place.
+    The input datamodel is modified in-place.
 
     Parameters
     ----------
-    input_datamodel : DataModel
-        Input science data. Updated in place.
-    failed_slitlets : list of Slit
+    input_datamodel : `~stdatamodels.jwst.datamodels.JwstDataModel`
+        Input science data. Updated in-place.
+    failed_slitlets : list of `~stdatamodels.jwst.transforms.Slit`
         Failed open slitlets.
     wcs_refnames : dict
         Reference file names used to calculate the WCS. Keys are reference
         file types; values are file paths.
 
     Returns
     -------
-    input_datamodel : DataModel
+    input_datamodel : `~stdatamodels.jwst.datamodels.JwstDataModel`
         Science data with DQ flags modified.
     """
     # Use the machinery in assign_wcs to create a WCS object for the bad shutters
@@ -142,7 +142,7 @@ def boundingbox_to_indices(data_shape, bounding_box):
     """
     Translate a bounding box to image indices.
 
-    Takes a bounding_box (tuple of tuples: ((x1, x2), (y1, y2)) and
+    Takes a ``bounding_box`` (tuple of tuples: ``((x1, x2), (y1, y2))``) and
     a datamodel and calculates the range of indices in the X and Y dimensions
     of the overlap between the bounding box and the datamodel's data array.
 
@@ -151,7 +151,7 @@ def boundingbox_to_indices(data_shape, bounding_box):
     data_shape : tuple
         The data shape for the input science datamodel.
     bounding_box : tuple of tuple
-        Bounding box returned from wcs object.
+        Bounding box returned from WCS object.
 
     Returns
     -------
@@ -176,7 +176,7 @@ def wcs_to_dq(wcs_array, flag):
     """
     Create a DQ subarray corresponding to a failed open slitlet.
 
-    The created array has the value `flag` wherever the WCS coordinates
+    The created array has the value ``flag`` wherever the WCS coordinates
     are valid (non-NaN) and 0 otherwise.
 
     Parameters
@@ -239,7 +239,7 @@ def create_slitlets(shutter_refname):
 
     Returns
     -------
-    slitlets : list of Slit
+    slitlets : list of `~stdatamodels.jwst.transforms.Slit`
         A list of slitlets. Each slitlet is a named tuple with elements
         ("name", "shutter_id", "dither_position", "xcen", "ycen", "ymin", "ymax",
         "quadrant", "source_id", "shutter_state", "source_name", "source_alias",

jwst/msaflagopen/msaflag_open.py

@@ -1,3 +1,5 @@
+"""Flag pixels affected by open MSA shutters in NIRSpec exposures."""
+
 import logging
 
 from stpipe.crds_client import reference_uri_to_cache_path
@@ -68,7 +70,7 @@ def create_reference_filename_dictionary(input_model):
 
     Parameters
     ----------
-    input_model : DataModel
+    input_model : `~stdatamodels.jwst.datamodels.JwstDataModel`
         Input data with WCS assigned.
 
     Returns