DOC: Complete API for linearity (spacetelescope#10439)

Author: pllim

docs/jwst/linearity/api_ref.rst

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

docs/jwst/linearity/arguments.rst

@@ -1,14 +1,14 @@
 Description
-============
+===========
 
-:Class: `jwst.linearity.LinearityStep`
+:Class: `jwst.linearity.linearity_step.LinearityStep`
 :Alias: linearity
 
 Assumptions
 -----------
 It is assumed that the input science exposure data for near-IR instruments
 have had the :ref:`superbias <superbias_step>` subtraction step applied,
-therefore the correction coefficients stored in the linearity reference files
+therefore the correction coefficients stored in the :ref:`linearity_reffile`
 for those instruments must have been derived from data that has also been
 bias subtracted.
 MIRI data, on the other hand, do not receive bias subtraction
@@ -30,8 +30,8 @@ for detector non-linearity. The correction is applied pixel-by-pixel,
 group-by-group, integration-by-integration within a science exposure.
 
 The correction is represented by an nth-order polynomial for
-each pixel in the detector, with n+1 arrays of coefficients read from the
-linearity reference file.
+each pixel in the detector, with ``n+1`` arrays of coefficients read from the
+:ref:`linearity_reffile`.
 
 The algorithm for correcting the observed pixel value in each group of an
 integration is currently of the form:
@@ -42,7 +42,7 @@ integration is currently of the form:
 where :math:`F` is the observed counts (in DN), :math:`c_n` are the polynomial
 coefficients, and :math:`F_\text{c}` is the corrected counts. There is no
 limit to the order of the polynomial correction; all coefficients contained in
-the reference file will be applied.
+the :ref:`linearity_reffile` will be applied.
 
 Upon successful completion of the linearity correction the S_LINEAR keyword is
 set to "COMPLETE".
@@ -54,16 +54,16 @@ Special Handling
    the linearity correction applied and the DQ flag "NO_LIN_CORR" is added to
    the science exposure PIXELDQ array.
 
-#. Pixels that have the "NO_LIN_CORR" flag set in the DQ array of the linearity
-   reference file will not have the correction applied and the "NO_LIN_CORR" flag
+#. Pixels that have the "NO_LIN_CORR" flag set in the DQ array of the
+   :ref:`linearity_reffile` will not have the correction applied and the "NO_LIN_CORR" flag
    is added to the science exposure PIXELDQ array.
 
 #. Pixel values that have the "SATURATED" flag set in a particular group of the
    science exposure GROUPDQ array will not have the linearity correction
    applied to that group. Any groups for that pixel that are not flagged as
    saturated will be corrected.
 
-The flags from the linearity reference file DQ array are propagated into the
+The flags from the :ref:`linearity_reffile` DQ array are propagated into the
 PIXELDQ array of the science exposure using a bitwise OR operation.
 
 NIRCam Frame 0
@@ -81,7 +81,11 @@ Subarrays
 This step handles input science exposures that were taken in subarray modes
 in a flexible way. If the reference data arrays are the same size as the
 science data, they will be applied directly. If there is a mismatch, the
-routine will extract a matching subarray from the reference file data arrays
+routine will extract a matching subarray from the :ref:`linearity_reffile` data arrays
 and apply them to the science data. Hence full-frame reference files can be
 used for both full-frame and subarray science exposures, or
 subarray-dependent reference files can be provided if desired.
+
+Step Arguments
+--------------
+The linearity correction has no step-specific arguments.

docs/jwst/linearity/description.rst

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

docs/jwst/linearity/index.rst

@@ -1,5 +1,5 @@
-Reference File Types
-====================
+Reference Files
+===============
 
 The ``linearity`` step uses a LINEARITY reference file.
 

docs/jwst/linearity/reference_files.rst

@@ -1,7 +1,7 @@
 .. _linearity_reffile:
 
 LINEARITY Reference File
--------------------------
+------------------------
 
 :REFTYPE: LINEARITY
 :Data model: `~stdatamodels.jwst.datamodels.LinearityModel`
@@ -14,7 +14,7 @@ coefficients.
 .. include:: ../includes/standard_keywords.inc
 
 Type Specific Keywords for LINEARITY
-+++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++
 In addition to the standard reference file keywords listed above,
 the following keywords are *required* in LINEARITY reference files,
 because they are used as CRDS selectors

docs/jwst/references_general/linearity_reffile.inc

@@ -7,12 +7,11 @@ LINEARITY is not applicable for instruments not in the table.
 All keywords used for file selection are *required*.
 
 ========== ==============================================================
-Instrument Keywords                                                       
+Instrument Keywords
 ========== ==============================================================
-FGS        INSTRUME, DETECTOR, SUBARRAY, DATE-OBS, TIME-OBS               
-MIRI       INSTRUME, DETECTOR, SUBARRAY, BAND, FILTER, DATE-OBS, TIME-OBS 
-NIRCam     INSTRUME, DETECTOR, SUBARRAY, DATE-OBS, TIME-OBS               
-NIRISS     INSTRUME, DETECTOR, SUBARRAY, DATE-OBS, TIME-OBS               
-NIRSpec    INSTRUME, DETECTOR, SUBARRAY, DATE-OBS, TIME-OBS               
+FGS        INSTRUME, DETECTOR, SUBARRAY, DATE-OBS, TIME-OBS
+MIRI       INSTRUME, DETECTOR, SUBARRAY, BAND, FILTER, DATE-OBS, TIME-OBS
+NIRCam     INSTRUME, DETECTOR, SUBARRAY, DATE-OBS, TIME-OBS
+NIRISS     INSTRUME, DETECTOR, SUBARRAY, DATE-OBS, TIME-OBS
+NIRSpec    INSTRUME, DETECTOR, SUBARRAY, DATE-OBS, TIME-OBS
 ========== ==============================================================
-

docs/jwst/references_general/linearity_selection.inc

@@ -17,15 +17,15 @@ def do_correction(output_model, lin_model):
 
     Parameters
     ----------
-    output_model : `~jwst.datamodels.RampModel`
+    output_model : `~stdatamodels.jwst.datamodels.RampModel`
         Science data to be corrected.
 
-    lin_model : `~jwst.datamodels.LinearityModel`
+    lin_model : `~stdatamodels.jwst.datamodels.LinearityModel`
         Linearity reference file model.
 
     Returns
     -------
-    output_model : `~jwst.datamodels.RampModel`
+    output_model : `~stdatamodels.jwst.datamodels.RampModel`
         Linearity corrected science data.
     """
     # Create the output model as a copy of the input

jwst/linearity/linearity.py

@@ -1,3 +1,5 @@
+"""Apply linearity correction to ramp data."""
+
 import logging
 
 from stdatamodels.jwst import datamodels