DM-15812: convert obs_decam to numpydoc

doc/.gitignore

@@ -0,0 +1,10 @@
+# Doxygen products
+html
+xml
+*.tag
+*.inc
+doxygen.conf
+
+# Sphinx products
+_build
+py-api

doc/SConscript

@@ -0,0 +1,3 @@
+# -*- python -*-
+from lsst.sconsUtils import scripts
+scripts.BasicSConscript.doc()

doc/conf.py

@@ -0,0 +1,13 @@
+"""Sphinx configuration file for an LSST stack package.
+
+This configuration only affects single-package Sphinx documenation builds.
+"""
+
+from documenteer.sphinxconfig.stackconf import build_package_configs
+import lsst.obs.decam
+
+
+_g = globals()
+_g.update(build_package_configs(
+    project_name='obs_decam',
+    version=lsst.obs.decam.version.__version__))

doc/index.rst

@@ -0,0 +1,12 @@
+################################
+obs_decam documentation preview
+################################
+
+.. This page is for local development only. It isn't published to pipelines.lsst.io.
+
+.. Link the index pages of package and module documentation directions (listed in manifest.yaml).
+
+.. toctree::
+   :maxdepth: 1
+
+   lsst.obs.decam/index

doc/lsst.obs.decam/index.rst

@@ -0,0 +1,53 @@
+.. _lsst.obs.decam:
+
+###############
+lsst.obs.decam
+###############
+
+.. Paragraph that describes what this Python module does and links to related modules and frameworks.
+
+Write description here
+
+.. _lsst.obs.decam-contributing:
+
+Contributing
+============
+
+``lsst.obs.decam`` is developed at https://github.com/lsst/obs_decam.
+You can find Jira issues for this module under the `example <https://jira.lsstcorp.org/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20obs_decam>`_ component.
+
+Task reference
+==============
+
+.. _lsst.obs.decam-command-line-tasks:
+
+Command-line tasks
+------------------
+
+.. lsst-cmdlinetasks::
+   :root: lsst.obs.decam
+
+.. _lsst.obs.decam-tasks:
+
+Tasks
+-----
+
+.. lsst-tasks::
+   :root: lsst.obs.decam
+   :toctree: tasks
+
+.. _lsst.obs.decam-configs:
+
+Configurations
+--------------
+
+.. lsst-configs::
+   :root: lsst.obs.decam
+   :toctree: configs
+
+.. _lsst.obs.decam-pyapi:
+
+Python API reference
+====================
+
+.. automodapi:: lsst.obs.decam

doc/lsst.obs.decam/tasks/lsst.obs.decam.crosstalk.DecamCrosstalkTask.rst

@@ -0,0 +1,17 @@
+.. lsst-task-topic:: lsst.obs.decam.crosstalk.DecamCrosstalkTask
+
+##################
+DecamCrosstalkTask
+##################
+
+``DecamCrosstalkTask`` applies crosstalk corrections to DECam images.
+
+Python API summary
+==================
+
+.. lsst-task-api-summary:: lsst.obs.decam.crosstalk.DecamCrosstalkTask
+
+Configuration fields
+====================
+
+.. lsst-task-config-fields:: lsst.obs.decam.crosstalk.DecamCrosstalkTask

doc/lsst.obs.decam/tasks/lsst.obs.decam.decamCpIsr.DecamCpIsrTask.rst

@@ -0,0 +1,17 @@
+.. lsst-task-topic:: lsst.obs.decam.decamCpIsr.DecamCpIsrTask
+
+##############
+DecamCpIsrTask
+##############
+
+``DecamCpIsrTask`` performs ISR using Community Pipeline Calibration Products MasterCals.
+
+Python API summary
+==================
+
+.. lsst-task-api-summary:: lsst.obs.decam.decamCpIsr.DecamCpIsrTask
+
+Configuration fields
+====================
+
+.. lsst-task-config-fields:: lsst.obs.decam.decamCpIsr.DecamCpIsrTask

doc/lsst.obs.decam/tasks/lsst.obs.decam.decamNullIsr.DecamNullIsrTask.rst

@@ -0,0 +1,17 @@
+.. lsst-task-topic:: lsst.obs.decam.decamNullIsr.DecamNullIsrTask
+
+################
+DecamNullIsrTask
+################
+
+``DecamNullIsrTask`` load an "instcal" exposure as a post-ISR CCD exposure.
+
+Python API summary
+==================
+
+.. lsst-task-api-summary:: lsst.obs.decam.decamNullIsr.DecamNullIsrTask
+
+Configuration fields
+====================
+
+.. lsst-task-config-fields:: lsst.obs.decam.decamNullIsr.DecamNullIsrTask

doc/lsst.obs.decam/tasks/lsst.obs.decam.ingest.DecamIngestTask.rst

@@ -0,0 +1,17 @@
+.. lsst-task-topic:: lsst.obs.decam.ingest.DecamIngestTask
+
+###############
+DecamIngestTask
+###############
+
+``DecamIngestTask`` ingests all specified DECam files and adds them to the registry.
+
+Python API summary
+==================
+
+.. lsst-task-api-summary:: lsst.obs.decam.ingest.DecamIngestTask
+
+Configuration fields
+====================
+
+.. lsst-task-config-fields:: lsst.obs.decam.ingest.DecamIngestTask

doc/lsst.obs.decam/tasks/lsst.obs.decam.ingest.DecamParseTask.rst

@@ -0,0 +1,18 @@
+.. lsst-task-topic:: lsst.obs.decam.ingest.DecamParseTask
+
+###############
+DecamParseTask
+###############
+
+``DecamParseTask`` parses an image filename to get the required information
+to put the file in the correct location and populate the registry.
+
+Python API summary
+==================
+
+.. lsst-task-api-summary:: lsst.obs.decam.ingest.DecamParseTask
+
+Configuration fields
+====================
+
+.. lsst-task-config-fields:: lsst.obs.decam.ingest.DecamParseTask

doc/lsst.obs.decam/tasks/lsst.obs.decam.ingestCalibs.DecamCalibsParseTask.rst

@@ -0,0 +1,19 @@
+.. lsst-task-topic:: lsst.obs.decam.ingestCalibs.DecamCalibsParseTask
+
+####################
+DecamCalibsParseTask
+####################
+
+``DecamCalibsParseTask`` parses a calibration image filename to get the
+required information to put the file in the correct location and populate the
+calibration registry.
+
+Python API summary
+==================
+
+.. lsst-task-api-summary:: lsst.obs.decam.ingestCalibs.DecamCalibsParseTask
+
+Configuration fields
+====================
+
+.. lsst-task-config-fields:: lsst.obs.decam.ingestCalibs.DecamCalibsParseTask

doc/lsst.obs.decam/tasks/lsst.obs.decam.isr.DecamIsrTask.rst

@@ -0,0 +1,17 @@
+.. lsst-task-topic:: lsst.obs.decam.isr.DecamIsrTask
+
+############
+DecamIsrTask
+############
+
+``DecamIsrTask`` applies ISR to DECam images.
+
+Python API summary
+==================
+
+.. lsst-task-api-summary:: lsst.obs.decam.isr.DecamIsrTask
+
+Configuration fields
+====================
+
+.. lsst-task-config-fields:: lsst.obs.decam.isr.DecamIsrTask

doc/manifest.yaml

@@ -0,0 +1,15 @@
+# Documentation manifest.
+
+# Name of this package
+# Also the name of the package documentation subdirectory.
+package: "obs_decam"
+
+# List of names of Python modules in this package.
+# For each module there is a corresponding module doc subdirectory.
+modules:
+  - "lsst.obs.decam"
+
+# Name of the static content directories (subdirectories of `_static`).
+# Static content directories are usually named after the package.
+statics:
+  - "_static/obs_decam"

python/lsst/obs/decam/crosstalk.py

@@ -20,7 +20,7 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-"""Apply crosstalk corrections to raw DECam images.
+"""Apply crosstalk corrections to DECam images.
 
 Some of this code is based on DECam_crosstalk.py, used for the THELI pipeline
 and written by Thomas Erben (private communication, 2018)
@@ -51,20 +51,36 @@ class DecamCrosstalkConfig(CrosstalkConfig):
     """
 
     def getSourcesAndCoeffsFile(self, filename='DECam_xtalk_20130606.txt'):
-        """Return directory containing the DECam_xtalk_20130606.txt file.
+        """File containing DECam crosstalk coefficients.
 
-        File containing DECam crosstalk coefficients. This text file is
-        provided by NOAO in a particular format with information
-        about the DECam crosstalk coefficients. It is available at
+        This text file is provided by NOAO in a particular format with
+        information about the DECam crosstalk coefficients. It is available at
         http://www.ctio.noao.edu/noao/content/DECam-Calibration-Files
+
+        Parameters
+        ----------
+        filename : `str`, optional
+            File containing the decam crosstalk coefficients, from NOAO.
+
+        Returns
+        -------
+        result : `str`
+            Full path to filename.
         """
         mapper = DecamMapper()
         packageName = mapper.getPackageName()
         packageDir = getPackageDir(packageName)
         return os.path.join(packageDir, 'decam', filename)
 
     def getSourcesAndCoeffs(self):
-        """Read crosstalk sources and coefficients from DECam-specific file
+        """Read crosstalk sources and coefficients from DECam-specific file.
+
+        Returns
+        -------
+        sources : `defaultdict`
+            Sources of crosstalk read from crosstalk_file.
+        coeffs : `dict`
+            Linear crosstalk coefficients corresponding to sources.
         """
         crosstalk_file = self.getSourcesAndCoeffsFile()
         sources = defaultdict(list)
@@ -226,7 +242,7 @@ class DecamCrosstalkIO(pipeBase.Task):
     _DefaultName = 'decamCrosstalkIO'
 
     def parseCrosstalkIOArgs(self):
-        """Parse command-line arguments to run the crosstalk correction alone
+        """Parse command-line arguments to run the crosstalk correction alone.
 
         Examples
         --------
@@ -242,7 +258,7 @@ def parseCrosstalkIOArgs(self):
         return parsed
 
     def runCrosstalkAlone(self):
-        """Utility for crosstalk correction directly on a DECam MEF file
+        """Utility for crosstalk correction directly on a DECam MEF file.
         """
         log = lsst.log.Log.getLogger('obs.decam.DecamCrosstalkIO')
         parsed = self.parseCrosstalkIOArgs()
@@ -272,16 +288,16 @@ def subtractCrosstalkIO(mef, sources, coeffs):
     Parameters
     ----------
     mef : `astropy.io.fits.hdu.hdulist.HDUList`
-        One DECam Multi-Extension FITS image
+        One DECam Multi-Extension FITS image.
     sources : `defaultdict`
-        Crosstalk source areas affecting flux in a certain victim area
+        Crosstalk source areas affecting flux in a certain victim area.
     coeffs : `list`
-        Linear crosstalk coefficients
+        Linear crosstalk coefficients.
 
     Returns
     -------
     mef : `astropy.io.fits.hdu.hdulist.HDUList`
-        New MEF image with crosstalk corrected data and updated header
+        New MEF image with crosstalk corrected data and updated header.
     """
     log = lsst.log.Log.getLogger('obs.decam.subtractCrosstalkIO')
     lowx = {}  # Lower x pixel index of given chip region