Add fgcmcal documentation tree.

Add task and config documentation and fix numpy doc-strings that were causing
problems in the automatic parsing.

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,12 @@
+"""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.fgcmcal
+
+
+_g = globals()
+_g.update(build_package_configs(
+    project_name='fgcmcal',
+    version=lsst.fgcmcal.version.__version__))

doc/index.rst

@@ -0,0 +1,14 @@
+#############################
+fgcmcal 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.fgcmcal/index

doc/lsst.fgcmcal/configs/lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsConfig.rst

@@ -0,0 +1,12 @@
+.. lsst-config-topic:: lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsConfig
+
+####################
+FgcmBuildStarsConfig
+####################
+
+.. _lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsConfig-configs:
+
+Configuration fields
+====================
+
+.. lsst-config-fields:: lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsConfig

doc/lsst.fgcmcal/configs/lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractConfig.rst

@@ -0,0 +1,12 @@
+.. lsst-config-topic:: lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractConfig
+
+########################
+FgcmCalibrateTractConfig
+########################
+
+.. _lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractConfig-configs:
+
+Configuration fields
+====================
+
+.. lsst-config-fields:: lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractConfig

doc/lsst.fgcmcal/configs/lsst.fgcmcal.fgcmFitCycle.FgcmFitCycleConfig.rst

@@ -0,0 +1,12 @@
+.. lsst-config-topic:: lsst.fgcmcal.fgcmFitCycle.FgcmFitCycleConfig
+
+####################
+FgcmFitCycleConfig
+####################
+
+.. _lsst.fgcmcal.fgcmFitCycle.FgcmFitCycleConfig-configs:
+
+Configuration fields
+====================
+
+.. lsst-config-fields:: lsst.fgcmcal.fgcmFitCycle.FgcmFitCycleConfig

doc/lsst.fgcmcal/configs/lsst.fgcmcal.fgcmLoadReferenceCatalog.FgcmLoadReferenceCatalogConfig.rst

@@ -0,0 +1,12 @@
+.. lsst-config-topic:: lsst.fgcmcal.fgcmLoadReferenceCatalog.FgcmLoadReferenceCatalogConfig
+
+##############################
+FgcmLoadReferenceCatalogConfig
+##############################
+
+.. _lsst.fgcmcal.fgcmLoadReferenceCatalog.FgcmLoadReferenceCatalogConfig-configs:
+
+Configuration fields
+====================
+
+.. lsst-config-fields:: lsst.fgcmcal.fgcmLoadReferenceCatalog.FgcmLoadReferenceCatalogConfig

doc/lsst.fgcmcal/configs/lsst.fgcmcal.fgcmMakeLut.FgcmMakeLutConfig.rst

@@ -0,0 +1,12 @@
+.. lsst-config-topic:: lsst.fgcmcal.fgcmMakeLut.FgcmMakeLutConfig
+
+#################
+FgcmMakeLutConfig
+#################
+
+.. _lsst.fgcmcal.fgcmMakeLut.FgcmMakeLutConfig-configs:
+
+Configuration fields
+====================
+
+.. lsst-config-fields:: lsst.fgcmcal.fgcmMakeLut.FgcmMakeLutConfig

doc/lsst.fgcmcal/configs/lsst.fgcmcal.fgcmOutputProducts.FgcmOutputProductsConfig.rst

@@ -0,0 +1,12 @@
+.. lsst-config-topic:: lsst.fgcmcal.fgcmOutputProducts.FgcmOutputProductsConfig
+
+########################
+FgcmOutputProductsConfig
+########################
+
+.. _lsst.fgcmcal.fgcmOutputProducts.FgcmOutputProductsConfig-configs:
+
+Configuration fields
+====================
+
+.. lsst-config-fields:: lsst.fgcmcal.fgcmOutputProducts.FgcmOutputProductsConfig

doc/lsst.fgcmcal/configs/lsst.fgcmcal.sedterms.Sedboundaryterm.rst

@@ -0,0 +1,12 @@
+.. lsst-config-topic:: lsst.fgcmcal.sedterms.Sedboundaryterm
+
+###############
+Sedboundaryterm
+###############
+
+.. _lsst.fgcmcal.sedterms.Sedboundaryterm-configs:
+
+Configuration fields
+====================
+
+.. lsst-config-fields:: lsst.fgcmcal.sedterms.Sedboundaryterm

doc/lsst.fgcmcal/configs/lsst.fgcmcal.sedterms.SedboundarytermDict.rst

@@ -0,0 +1,12 @@
+.. lsst-config-topic:: lsst.fgcmcal.sedterms.SedboundarytermDict
+
+###################
+SedboundarytermDict
+###################
+
+.. _lsst.fgcmcal.sedterms.SedboundarytermDict-configs:
+
+Configuration fields
+====================
+
+.. lsst-config-fields:: lsst.fgcmcal.sedterms.SedboundarytermDict

doc/lsst.fgcmcal/configs/lsst.fgcmcal.sedterms.Sedterm.rst

@@ -0,0 +1,12 @@
+.. lsst-config-topic:: lsst.fgcmcal.sedterms.Sedterm
+
+#######
+Sedterm
+#######
+
+.. _lsst.fgcmcal.sedterms.Sedterm-configs:
+
+Configuration fields
+====================
+
+.. lsst-config-fields:: lsst.fgcmcal.sedterms.Sedterm

doc/lsst.fgcmcal/configs/lsst.fgcmcal.sedterms.SedtermDict.rst

@@ -0,0 +1,12 @@
+.. lsst-config-topic:: lsst.fgcmcal.sedterms.SedtermDict
+
+###########
+SedtermDict
+###########
+
+.. _lsst.fgcmcal.sedterms.SedtermDict-configs:
+
+Configuration fields
+====================
+
+.. lsst-config-fields:: lsst.fgcmcal.sedterms.SedtermDict

doc/lsst.fgcmcal/index.rst

@@ -0,0 +1,61 @@
+.. py:currentmodule:: lsst.fgcmcal
+
+.. _lsst.fgcmcal:
+
+############
+lsst.fgcmcal
+############
+
+The ``lsst.fgcmcal`` module runs the Forward Global Calibration Method (FGCM) to perform global photometric survey calibration for LSST.  Please see `Burke, Rykoff, et al. 2018 <http://adsabs.harvard.edu/abs/2018AJ....155...41B>`_ for the paper describing the method.  This ``lsst.fgcmcal`` package wraps the third-party package `fgcm <https://github.com/lsst/fgcm/tree/lsst-dev>`_.
+
+.. _lsst.example.pythononly-using:
+
+Using lsst.fgcmcal
+=============================
+
+Please see the `cookbook <https://github.com/lsst/fgcmcal/tree/master/cookbook/README.md>`_ for a runthrough on how to use ``lsst.fgcmcal``.
+
+There are four tasks to be run in a typical global ``fgcmcal`` processing chain.  They are:
+
+#. Make a look-up table: :doc:`tasks/lsst.fgcmcal.fgcmMakeLut.FgcmMakeLutTask`
+
+#. Build the star lists: :doc:`tasks/lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask`
+
+#. Run the fitter: :doc:`tasks/lsst.fgcmcal.fgcmFitCycle.FgcmFitCycleTask`
+
+#. Output the final products: :doc:`tasks/lsst.fgcmcal.fgcmOutputProducts.FgcmOutputProductsTask`
+
+Alternatively, ``fgcmcal`` can be run on a single tract (with multi-band coverage), although the results will not be as robust as a full global calibration.  This can be run with :doc:`tasks/lsst.fgcmcal.fgcmCalibrateTract.FgcmCalibrateTractTask`, which will run all of the tasks above except for the making of the look-up table.
+
+.. _lsst.example.pythononly-contributing:
+
+Contributing
+============
+
+``lsst.fgcmcal`` is developed at https://github.com/lsst/fgcmcal.  You can find Jira issues for this module under the `fgcmcal <https://jira.lsstcorp.org/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20fgcmcal>`_ component.
+
+.. _lsst.example.pythononly-command-line-tasks:
+
+Command-line tasks
+------------------
+
+.. lsst-cmdlinetasks::
+   :root: lsst.fgcmcal
+
+.. _lsst.example.pythononly-tasks:
+
+Configurations
+--------------
+
+.. lsst-configs::
+   :root: lsst.fgcmcal
+   :toctree: configs
+
+.. _lsst.example.pythononly-pyapi:
+
+Python API reference
+====================
+
+.. automodapi:: lsst.fgcmcal
+   :no-main-docstr:
+   :no-inheritance-diagram:

doc/lsst.fgcmcal/tasks/lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask.rst

@@ -0,0 +1,127 @@
+.. lsst-task-topic:: lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask
+
+##################
+FgcmBuildStarsTask
+##################
+
+``FgcmBuildStarsTask`` finds all the single-visit sources in a repository (or a subset based on command-line parameters) and extracts all the potential photometric calibration stars for input into fgcm.  This task additionally uses fgcm to match star observations into unique stars, and performs as much cleaning of the input catalog as possible.  A tutorial on the steps of running ``fgcmcal`` are found in the `cookbook <https://github.com/lsst/fgcmcal/tree/master/cookbook>`_.
+
+The ``fgcmcal`` code runs on calexp source catalogs from visits constrained by the ``--id`` parameter on the command line.  Best results are obtained when ``fgcmcal`` is run with full visits.
+
+In Gen2, due to limitations of the Gen2 Butler, optimal performance is obtained by specifying a single "reference" ccd on the command line (e.g. ``ccd=13``) and setting the config variable ``checkAllCcds = True`` (which is the default).  The alternative is to specify all the desired CCDs and set ``checkAllCcds = False``, e.g., ``ccd=0..8^10..103``.  However, this is slower than the first option, and the improvement in speed in the first option is greater the more visits are specified.  If instead you want to process all the visits in a rerun selected by filter, field, or some other dataid field, then by using a reference ccd and setting ``checkAllCcds = True`` you can speed things up by a factor of approximately 100 relative to the alternative (naming CCDs specifically).
+
+Be aware that if a visit does not have a ``calexp`` available with the given reference CCD then it will be skipped.  If this is possibly an issue, multiple reference ccds can be specified on the command line, although performance will degrade the more are specified.
+
+At the current time, ``fgcmcal`` does not support Gen3.
+
+This is the second task in a typical ``fgcmcal`` processing chain.  The first is :doc:`lsst.fgcmcal.fgcmMakeLut.FgcmMakeLutTask`, the third is :doc:`lsst.fgcmcal.fgcmFitCycle.FgcmFitCycleTask`, and the fourth is :doc:`lsst.fgcmcal.fgcmOutputProducts.FgcmOutputProductsTask`.
+
+``FgcmBuildStarsTask`` is available as a :ref:`command-line task <pipe-tasks-command-line-tasks>`, :command:`fgcmBuildStars.py`.
+
+.. _lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask-summary:
+
+Processing summary
+==================
+
+.. If the task does not break work down into multiple steps, don't use a list.
+.. Instead, summarize the computation itself in a paragraph or two.
+
+``FgcmBuildStarsTask`` runs this sequence of operations:
+
+#. Finds unique visits and collates visit metadata, including exposure time, pointing, typical psf size, background level.
+
+#. Reads in all sources, selecting good stars according to the chosen source selector.
+
+#. Matches sources internally across bands to get a unique multi-band list of possible calibration stars.
+
+#. Matches possible calibration stars to a reference catalog.
+
+#. All results are stored in the output repo ``fgcm-process`` directory.
+
+
+.. _lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask-cli:
+
+fgcmBuildStars.py command-line interface
+========================================
+
+.. code-block:: text
+
+   fgcmBuildStars.py REPOPATH [@file [@file2 ...]] [--output OUTPUTREPO | --rerun RERUN] [--id] [other options]
+
+Key arguments:
+
+:option:`REPOPATH`
+   The input Butler repository's URI or file path.
+
+Key options:
+
+:option:`--id`:
+   The data IDs to process.
+
+.. seealso::
+
+   See :ref:`command-line-task-argument-reference` for details and additional options.
+
+.. _lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask-api:
+
+Python API summary
+==================
+
+.. lsst-task-api-summary:: lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask
+
+.. _lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask-butler:
+
+Butler datasets
+===============
+
+When run as the ``fgcmBuildStars.py`` command-line task, or directly through the `~lsst.fgcmcal.FgcmBuildStarsTask.runDataRef` method, ``FgcmBuildStarsTask`` obtains datasets from the input Butler data repository and persists outputs to the output Butler data repository.
+Note that configurations for ``FgcmBuildStarsTask``, and its subtasks, affect what datasets are persisted and what their content is.
+
+.. _lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask-butler-inputs:
+
+Input datasets
+--------------
+
+``src``
+    Full-depth source catalog (`lsst.afw.table`) produced by `ProcessCcdTask`
+``calexp``
+    Calibrated exposure produced by `ProcessCcdTask` (for exposure metadata)
+``fgcmLookupTable``
+    FGCM look-up table produced by :doc:`lsst.fgcmcal.fgcmMakeLut.FgcmMakeLutTask`
+
+.. _lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask-butler-outputs:
+
+Output datasets
+---------------
+
+``fgcmVisitCatalog``
+    Catalog (`lsst.afw.table`) of visit metadata
+``fgcmStarObservations``
+    Catalog of star observations
+``fgcmStarIds``
+    Catalog of unique star ids, positions, and number of observations
+``fgcmStarIndices``
+    Catalog of indices linking unique star ids to star observations
+``fgcmReferenceStars``
+    Catalog of reference stars matched to unique star ids.
+
+.. _lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask-subtasks:
+
+Retargetable subtasks
+=====================
+
+.. lsst-task-config-subtasks:: lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask
+
+.. _lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask-configs:
+
+Configuration fields
+====================
+
+.. lsst-task-config-fields:: lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask
+
+.. _lsst.fgcmcal.fgcmBuildStars.FgcmBuildStarsTask-examples:
+
+Examples
+========
+
+See the `cookbook <https://github.com/lsst/fgcmcal/tree/master/cookbook/README.md>`_ for worked examples.