Merge pull request #135 from kammerje/rtd

Attempting to resolve readthedocs API issues
spacetelescope · Jan 8, 2024 · 82b4e10 · 82b4e10
2 parents fc66a5d + a3a59bc
commit 82b4e10
Show file tree

Hide file tree

Showing 10 changed files with 66 additions and 51 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -23,18 +23,9 @@
 import matplotlib
 matplotlib.use("agg")
 
-# Read in package version, without importing this package directly
-# (to avoid needing to install all the webbpsf datafiles as part of the readthedocs build)
-# This might also use sphinx-pyproject eventually, tbd
-from pkg_resources import get_distribution
-version = get_distribution('spaceKLIP').version
-#import spaceKLIP
-#version = spaceKLIP.__version__
-
-# Hack together a WEBBPSF_PATH and version file to avoid API compilation errors
-os.environ['WEBBPSF_PATH'] = '../'
-with open('../version.txt', 'w') as file:
-    file.write('9.9.9')
+import spaceKLIP
+
+version = spaceKLIP.__version__
 
 # -- General configuration ------------------------------------------------
 # Add any Sphinx extension module names here, as strings. They can be
@@ -45,7 +36,7 @@
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon',
+    'sphinx_automodapi.automodapi',
     'nbsphinx'
     # 'sphinx.ext.githubpages',
 ]

diff --git a/docs/source/modules.rst b/docs/source/modules.rst
diff --git a/docs/source/spaceKLIP.rst b/docs/source/spaceKLIP.rst
@@ -57,14 +57,6 @@ spaceKLIP.imagetools module
    :undoc-members:
    :show-inheritance:
 
-spaceKLIP.make\_psfmasks module
--------------------------------
-
-.. automodule:: spaceKLIP.make_psfmasks
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 spaceKLIP.mast module
 ---------------------
 

diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -3,4 +3,5 @@ sphinx
 pandoc
 nbsphinx
 sphinx-rtd-theme
-webbpsf_ext
+webbpsf_ext
+sphinx_automodapi
diff --git a/spaceKLIP/classpsfsubpipeline.py b/spaceKLIP/classpsfsubpipeline.py
@@ -47,23 +47,26 @@ def run_obs(database,
     kwargs : dict, optional
         Keyword arguments for the classical PSF subtraction method. Available
         keywords are:
+
         - combine_dithers : bool, optional
             Combine all dither positions into a single reference PSF or
             subtract each dither position individually? The default is True.
         - save_rolls : bool, optional
             Save each processed roll separately? The default is False.
         - mask_bright : float, optional
             Mask all pixels brighter than this value before minimizing the
-            PSF subtraction residuals.
+            PSF subtraction residuals. 
+
         The default is {}.
+
     subdir : str, optional
         Name of the directory where the data products shall be saved. The
         default is 'psfsub'.
-    
+
     Returns
     -------
     None.
-    
+
     """
 
     # Check input.

diff --git a/spaceKLIP/coron1pipeline.py b/spaceKLIP/coron1pipeline.py
@@ -462,6 +462,7 @@ def do_pseudo_refpix(self,
         -------
         res : jwst.datamodel
             Output JWST datamodel.
+
         """
 
         # Get number of custom reference pixel rows & columns.
@@ -527,14 +528,15 @@ def run_single_file(fitspath, output_dir, steps={}, verbose=False, **kwargs):
     WARNING: Will overwrite exiting files.
 
     This customized implementation can:
+
     - Do a custom saturation correction where only the bottom/top/left/right
       and not the diagonal pixels next to a saturated pixel are flagged.
     - Do a pseudo reference pixel correction. Therefore, flag the requested
       edge rows and columns as reference pixels, run the JWST stage 1 refpix
       step, and unflag the pseudo reference pixels again. Only applicable for
       subarray data.
     - Remove 1/f noise spatial striping in NIRCam data.
-    
+
     Parameters
     ----------
     fitspath : str
@@ -545,6 +547,7 @@ def run_single_file(fitspath, output_dir, steps={}, verbose=False, **kwargs):
         See here for how to use the steps parameter:
         https://jwst-pipeline.readthedocs.io/en/latest/jwst/user_documentation/running_pipeline_python.html#configuring-a-pipeline-step-in-python
         Custom step parameters are:
+
         - saturation/grow_diagonal : bool, optional
             Flag also diagonal pixels (or only bottom/top/left/right)? 
             The default is True.
@@ -563,6 +566,7 @@ def run_single_file(fitspath, output_dir, steps={}, verbose=False, **kwargs):
             Save the calibrated ramp? The default is False.
 
         Additional useful step parameters:
+
         - saturation/n_pix_grow_sat : int, optional
             Number of pixels to grow for saturation flagging. Default is 1.
         - ramp_fit/suppress_one_group : bool, optional
@@ -621,7 +625,7 @@ def run_single_file(fitspath, output_dir, steps={}, verbose=False, **kwargs):
     Returns
     -------
     Pipeline output, either rate or rateint data model.
-    
+
     """
 
     from webbpsf_ext.analysis_tools import nrc_ref_info
@@ -730,6 +734,7 @@ def run_obs(database,
     """
     Run the JWST stage 1 detector pipeline on the input observations database.
     This customized implementation can:
+
     - Do a custom saturation correction where only the bottom/top/left/right
       and not the diagonal pixels next to a saturated pixel are flagged.
     - Do a pseudo reference pixel correction. Therefore, flag the requested
@@ -746,6 +751,7 @@ def run_obs(database,
         See here for how to use the steps parameter:
         https://jwst-pipeline.readthedocs.io/en/latest/jwst/user_documentation/running_pipeline_python.html#configuring-a-pipeline-step-in-python
         Custom step parameters are:
+
         - saturation/grow_diagonal : bool, optional
             Flag also diagonal pixels (or only bottom/top/left/right)? 
             The default is True.
@@ -764,6 +770,7 @@ def run_obs(database,
             Save the calibrated ramp? The default is False.
 
         Additional useful step parameters:
+
         - saturation/n_pix_grow_sat : int, optional
             Number of pixels to grow for saturation flagging. Default is 1.
         - ramp_fit/suppress_one_group : bool, optional
@@ -772,7 +779,8 @@ def run_obs(database,
         - ramp_fit/maximum_cores : str, optional
             max number of parallel processes to create during ramp fitting.
             'none', 'quarter', 'half', or 'all'. Default: 'quarter'.
-        The default is {}. 
+
+        Default is {}.
         Each of these parameters can be passed directly through `kwargs`.
     subdir : str, optional
         Name of the directory where the data products shall be saved. The
@@ -832,7 +840,7 @@ def run_obs(database,
     Returns
     -------
     None.
-    
+
     """
 
     # Set output directory.

diff --git a/spaceKLIP/imagetools.py b/spaceKLIP/imagetools.py
@@ -490,9 +490,6 @@ def subtract_median(self,
         subdir : str, optional
             Name of the directory where the data products shall be saved. The
             default is 'medsub'.
-        
-       None.
-        
         method : str
             'robust' for a robust median after masking out bright stars,
             'sigma_clipped' for another version of robust median using astropy sigma_clipped_stats on the whole image,
@@ -784,23 +781,26 @@ def fix_bad_pixels(self,
                        restrict_to=None):
         """
         Identify and fix bad pixels.
-        
+
         Parameters
         ----------
         method : str, optional
             Sequence of bad pixel identification and cleaning methods to be run
             on the data. Different methods must be joined by a '+' sign without
             whitespace. Available methods are:
+
             - bpclean: use sigma clipping to identify additional bad pixels.
             - custom: use a custom bad pixel map.
             - timemed: replace pixels which are only bad in some frames with
                        their median value from the good frames.
             - dqmed: replace bad pixels with the median value of their
                      surrounding good pixels.
             - medfilt: replace bad pixels with an image plane median filter.
+
             The default is 'timemed+dqmed+medfilt'.
         bpclean_kwargs : dict, optional
             Keyword arguments for the 'bpclean' method. Available keywords are:
+
             - sigclip : float, optional
                 Sigma clipping threshold. The default is 5.
             - shift_x : list of int, optional
@@ -809,6 +809,7 @@ def fix_bad_pixels(self,
             - shift_y : list of int, optional
                 Pixels in y-direction to which each pixel shall be compared to.
                 The default is [-1, 0, 1].
+
             The default is {}.
         custom_kwargs : dict, optional
             Keyword arguments for the 'custom' method. The dictionary keys must
@@ -817,21 +818,27 @@ def fix_bad_pixels(self,
             same shape as the corresponding data. The default is {}.
         timemed_kwargs : dict, optional
             Keyword arguments for the 'timemed' method. Available keywords are:
+
             - n/a
+
             The default is {}.
         dqmed_kwargs : dict, optional
             Keyword arguments for the 'dqmed' method. Available keywords are:
+
             - shift_x : list of int, optional
                 Pixels in x-direction from which the median shall be computed.
                 The default is [-1, 0, 1].
             - shift_y : list of int, optional
                 Pixels in y-direction from which the median shall be computed.
                 The default is [-1, 0, 1].
+
             The default is {}.
         medfilt_kwargs : dict, optional
             Keyword arguments for the 'medfilt' method. Available keywords are:
+
             - size : int, optional
                 Kernel size of the median filter to be used. The default is 4.
+
             The default is {}.
         types : list of str, optional
             List of data types for which bad pixels shall be identified and
@@ -844,7 +851,7 @@ def fix_bad_pixels(self,
         Returns
         -------
         None.
-        
+
         """
 
         # Set output directory.
@@ -951,6 +958,7 @@ def find_bad_pixels_bpclean(self,
             be modified by the routine.
         bpclean_kwargs : dict, optional
             Keyword arguments for the 'bpclean' method. Available keywords are:
+
             - sigclip : float, optional
                 Sigma clipping threshold. The default is 5.
             - shift_x : list of int, optional
@@ -959,12 +967,13 @@ def find_bad_pixels_bpclean(self,
             - shift_y : list of int, optional
                 Pixels in y-direction to which each pixel shall be compared to.
                 The default is [-1, 0, 1].
+
             The default is {}.
         
         Returns
         -------
         None.
-        
+
         """
 
         # Check input.
@@ -1152,18 +1161,20 @@ def fix_bad_pixels_dqmed(self,
             the routine to exclude the fixed bad pixels.
         dqmed_kwargs : dict, optional
             Keyword arguments for the 'dqmed' method. Available keywords are:
+
             - shift_x : list of int, optional
                 Pixels in x-direction from which the median shall be computed.
                 The default is [-1, 0, 1].
             - shift_y : list of int, optional
                 Pixels in y-direction from which the median shall be computed.
                 The default is [-1, 0, 1].
+
             The default is {}.
         
         Returns
         -------
         None.
-        
+
         """
 
         # Check input.
@@ -1240,14 +1251,16 @@ def fix_bad_pixels_medfilt(self,
             the routine to exclude the fixed bad pixels.
         medfilt_kwargs : dict, optional
             Keyword arguments for the 'medfilt' method. Available keywords are:
+
             - size : int, optional
                 Kernel size of the median filter to be used. The default is 4.
+
             The default is {}.
-        
+
         Returns
         -------
         None.
-        
+
         """
 
         # Check input.

diff --git a/spaceKLIP/plotting.py b/spaceKLIP/plotting.py
@@ -314,7 +314,10 @@ def display_coron_image(filename):
 def display_coron_dataset(database, restrict_to=None, save_filename=None, stage3=None):
     """
     Display multiple files in a coronagraphic dataset.
-    
+
+    # TODO potentially provide other ways of filtering the data, e.g. to show
+    only the PSF stars or only references, etc.
+
     Parameters
     ----------
     database : spaceklip.Database
@@ -325,13 +328,11 @@ def display_coron_dataset(database, restrict_to=None, save_filename=None, stage3
         Most simply, set this to a filter name to only plot images with that filter.
     save_filename : str
         If provided, the plots will be saved to a PDF file with this name.
-    # TODO potentially provide other ways of filtering the data, e.g. to show
-    only the PSF stars or only references, etc.
     
     Returns
     -------
     None.
-    
+
     """
 
     if save_filename:

diff --git a/spaceKLIP/pyklippipeline.py b/spaceKLIP/pyklippipeline.py
@@ -49,6 +49,7 @@ def run_obs(database,
     kwargs : dict, optional
         Keyword arguments for the pyklip.parallelized.klip_dataset method.
         Available keywords are:
+
         - mode : list of str, optional
             Subtraction modes that shall be looped over. Possible values are
             'ADI', 'RDI', and 'ADI+RDI'. The default is ['ADI+RDI'].
@@ -68,6 +69,7 @@ def run_obs(database,
             Verbose mode? The default is False.
         - save_rolls : bool, optional
             Save each processed roll separately? The default is False.
+
         The default is {}.
     subdir : str, optional
         Name of the directory where the data products shall be saved. The
@@ -76,7 +78,7 @@ def run_obs(database,
     Returns
     -------
     None.
-    
+
     """
 
     # Check input.