RTD sphinx format updates

doc/source/conf.py

@@ -25,6 +25,8 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0,os.path.abspath('.'))
 
+autodoc_mock_imports = ['astropy', 'scipy', 'astroquery', 'pysiaf', 'stsci']
+
 # -- General configuration -----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions

doc/source/defringe.rst

@@ -70,9 +70,9 @@ the ratio of the data to the model for a given wavelength range.
   :width: 700
   :alt: Effectiveness of the Defringing Tools on an observation of GD71
 
-------------
+--------
 Routines
-------------
+--------
 
 .. currentmodule:: stistools.defringe
 .. automodule:: stistools.defringe

doc/source/index.rst

@@ -17,8 +17,8 @@ tools are in active development, so there is more to come.
     be in-sync with the
     `STIS Data Handbook <http://www.stsci.edu/hst/stis/documents/handbooks/currentDHB/>`_.
 
-Relationship to the IRAF/PyRAF stis Package
-*******************************************
+Relationship to the IRAF/PyRAF `stis` Package
+*********************************************
 
 The intent of this package is to provide the user community with many of the useful tools contained within the original IRAF/PyRAF
 stis package in Python. This is consistent with a larger effort to transition the user community from IRAF/PyRAF to Python,
@@ -68,10 +68,8 @@ for getting started.
    Defringe Examples <defringe_examples.rst>
 
 
-==================
-Indices and tables
-==================
+Indices and Tables
+******************
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`

stistools/ctestis.py

@@ -94,48 +94,48 @@ def ctestis(ycol, net, sky, stisimage=None, mjd=None, nread=None,
 
     Parameters
     ----------
-    ycol : arr
+    ycol: arr
         Y-column # of object
-    net : arr
+    net: arr
         Net photometric counts (background subtracted) measured from science image
         and scaled to cosmic-ray split exposure time (from which sky is measured)
-    sky : arr
+    sky: arr
         Single-pixel sky-background estimate measured from individual cosmic-ray
         split, bias- and dark-subtracted, flat-fielded images (flt.fits) with no 
         sky subtraction
-    stisimage : str, optional
+    stisimage: str, optional
         The name of the SX2 file from which to pull the header keywords.
-    mjd : float, optional
+    mjd: float, optional
         Modified julian date corresponding to the start time of the 1st
         exposure, corresponds to the TEXPSTRT keyword. If stisimage file is
         defined TEXPSTRT keyword will overwrite any provided mjd value.
-    nread : int, optional
+    nread: int, optional
         Number of image sets combined during CR rejection, corresponds to the
         NCOMBINE keyword. If stisimage file is defined NCOMBINE keyword will
         overwrite any provided nread value.
-    ybin : int , optional
+    ybin: int , optional
         Axis2 data bin size in unbinned detector pixels, corresponds to the
         BINAXIS2 keyword. If stisimage file is defined BINAXIS2 keyword will
         overwrite any provided ybin value.
-    gain : float, optional
+    gain: float, optional
         The image gain, corresponds to the CCDGAIN keyword.  If stisimage file
         is defined the CCDGAIN keyword will overwrite any provided gain value.
         If the gain is 4.0, it will be upated to 4.08.
-    amp : str, optional
+    amp: str, optional
         The amplifier used for the observation (default 'D').  Ignored if
         stisimage is provided.
-    sx2 : bool, optional
+    sx2: bool, optional
         Force the procedure to remove the top/bottom 38 rows. This is
         automatically done if the file in stisname contains '_sx2'. Default
         values is False
 
     Returns
     -------
-    fluxc : arr
+    fluxc: arr
         The empirically-corrected flux (counts)
-    dmagc : arr
+    dmagc: arr
         The empirical photometric correction (delta mag)
-    dyc : arr
+    dyc: arr
         The empirical astrometric correction (delta pixels)
     """
 

stistools/evaldisp.py

@@ -9,20 +9,20 @@ def newton(x, coeff, cenwave, niter=4):
     in this file assumes that the grating is first order.
 
     Parameters
-    -----------
-    x : float or ndarray
+    ----------
+    x: float or ndarray
         a single pixel number or an array of pixel numbers
-    coeff : array_like object
+    coeff: array_like object
         a list of eight elements containing the
         dispersion coefficients as read from a STIS _dsp.fits table
-    cenwave : int or float
+    cenwave: int or float
         central wavelength, in Angstroms
-    niter : int
+    niter: int
         number of iterations
 
     Returns
     -------
-    wavelength : float or ndarray
+    wavelength: float or ndarray
         a single wavelength or an array (numarray) of wavelengths,
         in Angstroms
     """
@@ -62,18 +62,18 @@ def evalDisp(coeff, wl):
     but this function converts to zero-indexed pixels.
 
     Parameters
-    -----------
-    coeff : array_like object
+    ----------
+    coeff: array_like object
         a list of eight elements containing the
         dispersion coefficients as read from a STIS _dsp.fits table
 
-    wl : float or ndarray
+    wl: float or ndarray
         a single wavelength or an array (numarray) of wavelengths,
         in Angstroms
 
     Returns
-    --------
-    pix_number : float or ndarray
+    -------
+    pix_number: float or ndarray
         the pixel number (or array of pixel numbers) corresponding
         to the input wavelength(s); note that these are zero indexed
     """

stistools/gettable.py

@@ -26,25 +26,25 @@ def getTable(table, filter, sortcol=None,
     but more than one row matches the filter.
 
     Parameters
-    -----------
-    table : string
+    ----------
+    table: str
         name of the reference table
-    filter : dict
+    filter: dict
         each key is a column name, and the corresponding value
         is a possible table value in that column
-    sortcol : string
+    sortcol: str
         the name of a column on which to sort the table rows
         (if there is more than one matching row), or None to disable sorting
-    exactly_one : bool
+    exactly_one: bool
         set this to True if there must be one and only one
         matching row
-    at_least_one : bool
+    at_least_one: bool
         set this to True if there must be at least one
         matching row
 
     Returns
     -------
-    match_rows : rec_array
+    match_rows: rec_array
         an array of the rows of the table that match the filter;
         note that if only one row matches the filter, the function value
         will still be an array
@@ -130,12 +130,12 @@ def rotateTrace(trace_info, expstart):
     """Rotate a2displ, if MJD and DEGPERYR are in the trace table.
 
     Parameters
-    -----------
-    trace_info : rec_array
+    ----------
+    trace_info: rec_array
         an array of the relevant rows of the table;
         the A2DISPL column will be modified in-place if the MJD and
         DEGPERYR columns are present
-    expstart : float
+    expstart: float
         exposure start time (MJD)
     """
 

stistools/inttag.py

@@ -97,10 +97,6 @@ def inttag(tagfile, output, starttime=None, increment=None,
 
         verbose: bool
             Print additional info?
-
-        Returns
-        -------
-
 """
     # Open Input File (_tag.fits)
     with fits.open(tagfile) as tag_hdr:
@@ -311,17 +307,13 @@ def exp_range(starttime, stoptime, events_data, gti_data, tzero_mjd):
             to non-GTI time (if the user is not using allevents).
 
         expstart: float
-
             Start time of the imset exposure
 
         expstop: float
-
             Stop time of the imset exposure
 
         good_events: float
             The events list within the imset exposure time and within the GTIs.
-
-
 """
     sec_per_day = (1*u.day).to(u.second).value
     imset_events = events_data[(events_data['TIME'] > starttime) * (events_data['TIME'] < stoptime)]  # within imset

stistools/r_util.py

@@ -9,18 +9,18 @@ def expandFileName(filename):
     """Expand environment variable in a file name.
 
     If the input file name begins with either a Unix-style or IRAF-style
-    environment variable (e.g. $lref/name_dqi.fits or lref$name_dqi.fits
+    environment variable (e.g. ``$lref/name_dqi.fits`` or ``lref$name_dqi.fits``
     respectively), this routine expands the variable and returns a complete
     path name for the file.
 
     Parameters
-    -----------
-    filename : str
+    ----------
+    filename: str
         A file name, possibly including an environment variable.
 
     Returns
-    --------
-    fullname : str
+    -------
+    fullname: str
         The file name with environment variable expanded.
     """
 
@@ -48,17 +48,17 @@ def interpolate(x, values, xp):
     value in values will be returned.
 
     Parameters
-    -----------
-    x : a sequence object, e.g. an array, int or float
+    ----------
+    x: a sequence object, e.g. an array, int or float
         Array of independent variable values.
-    values :  a sequence object, e.g. an array (not character)
+    values:  a sequence object, e.g. an array (not character)
         Array of dependent variable values.
-    xp : int or float
+    xp: int or float
         Independent variable value at which to interpolate.
 
     Returns
     -------
-    interp_vals : the same type as one element of values
+    interp_vals: the same type as one element of values
         Linearly interpolated value.
 
     """

stistools/radialvel.py

@@ -18,17 +18,17 @@ def radialVel(ra_targ, dec_targ, mjd):
     in the direction toward the target.
 
     Parameters
-    -----------
-    ra_targ : float
+    ----------
+    ra_targ: float
         right ascension of the target (degrees)
-    dec_targ : float
+    dec_targ: float
         declination of the target (degrees)
-    mjd : float
+    mjd: float
         Modified Julian Date at the time of observation
 
     Returns
-    --------
-    radial_vel : float
+    -------
+    radial_vel: float
         the radial velocity in km/s
     """
 
@@ -96,12 +96,12 @@ def earthVel(mjd):
 
     Parameters
     ----------
-    mjd : float
+    mjd: float
         time, Modified Julian Date
 
     Returns
     -------
-    vel :  ndarray
+    vel:  ndarray
         the velocity vector of the Earth around the Sun, in
         celestial coordinates (shape=(3,),ndtype=float64)
     """
@@ -173,15 +173,15 @@ def precess(mjd, target):
     .. [2] J.H. Lieske, 1979, Astron & Astrophys vol 73, 282-284.
 
     Parameters
-    -----------
-    mjd : float
+    ----------
+    mjd: float
         time, Modified Julian Date
-    target : array_like object
+    target: array_like object
         unit vector pointing toward the target, J2000 coordinates
 
     Returns
     -------
-    vector : ndarray
+    vector: ndarray
         the target vector (or matrix) precessed to mjd as an
         array object of type float64 and the same shape as target,
         i.e. either (3,) or (n,3)

stistools/sshift.py

@@ -49,31 +49,31 @@ def sshift(input, output=None, shifts=None, platescale=None,
 
 Parameters
 ----------
-input : list
+input: list
     A list of input filenames.  These must be STIS flat-
     fielded (_flt) image FITS files.  This argument will accept a
     single filename or a list of filenames.
-shifts : list, optional
+shifts: list, optional
     A list of integers indicating the number of rows to shift
     each image of each file in the cross-dispersion (Y-) direction.
-platescale : float, optional
+platescale: float, optional
     The size of a pixel in arcseconds.  Used to convert
     the value of the POSTARG2 keyword to pixels.
-tolerance : float, optional
+tolerance: float, optional
     The allowed difference between calculated shifts and
     integer pixel shifts (fraction of pixel).
 
 Returns
 -------
-output : list, optional
+output: list, optional
     A list of output filenames. The number of output
     filenames must match the number of input filenames.  If no output
     is given, then the _flt substring of the input file is replace by
     the _sfl substring to create an output file.  This option will
     accept a single filename or a list of filenames.
 
 Notes
-------
+-----
 Author:
   - Paul Barrett (STScI)