Merge pull request #294 from lsst/tickets/DM-37555

DM-37555: Update pipeline documentation for image differencing

doc/lsst.ip.diffim/AL_implementation.rst

@@ -40,9 +40,11 @@ Basis functions
 Solving for the matching kernel starts with the generation of the
 basis functions. The number of basis functions and the properties of
 the Gaussian bases (e.g. widths in pixels) are determined in
-`lsst.ip.diffim.makeKernelBasisList.generateAlardLuptonBasisList`. The
-decision logic depends on configuration and psf fwhm values of the
-images, some details is given in the function API documentation.
+`lsst.ip.diffim.makeKernelBasisList.generateAlardLuptonBasisList`. 
+The full config for this is being set in the module 
+`lsst.ip.diffim.psfMatch` config classes. The decision logic depends 
+on this configuration and psf fwhm values of the images, some details 
+are given in the function API documentation.
 
 .. TODO More details about the basis function generation
 

doc/lsst.ip.diffim/index.rst

@@ -6,7 +6,26 @@
 lsst.ip.diffim
 ##############
 
-The ``lsst.ip.diffim`` module provides algorithms for astronomical image differencing.
+.. Paragraph that describes what this Python module does and links to related modules and frameworks.
+
+The ``lsst.ip.diffim`` module provides algorithms and utilities for astronomical **image differencing** and **transient detection**.
+
+.. _lsst.ip.diffimg-overview:
+
+Overview of lsst.ip.diffim
+==========================
+
+.. toctree linking to the basic overview of the package
+
+.. toctree::
+   :maxdepth: 1 
+
+.. toctree::
+   :maxdepth: 1 
+
+   overview_ipdiffim
+   AL_implementation
+
 
 .. _lsst.ip.diffim-using:
 
@@ -15,14 +34,47 @@ Using lsst.ip.diffim
 
 .. toctree linking to topics related to using the module's APIs.
 
-.. toctree::
+.. toctree
    :maxdepth: 1
 
-.. toctree::
+.. toctree
    :maxdepth: 1
 
-   code_notes
-   AL_implementation
+Production pipelines
+--------------------
+
+This package is used in production pipelines like ``lsst.ap.pipe`` and ``lsst.drp.pipe``, designed for processing large collections of survey data.
+
+For an example of how the two primary `~lsst.pipe.base.PipelineTasks`  in this package (`~lsst.ip.diffim.AlardLuptonSubtractTask` and `~lsst.ip.diffim.DetectAndMeasureTask`) are used in a production pipeline, see `ap_pipe/pipelines/ApPipe.yaml`.
+
+
+Single frame processing
+-----------------------
+
+Single image frame usage can be carried out by importing the `~lsst.ip.diffim` as a library of tasks, as the following example shows:
+
+.. code-block:: python
+
+   from lsst.ip.diffim import subtractImages
+
+   ...
+   subtract_task = subtractImages.AlardLuptonSubtractTask()
+
+   subtraction = subtract_task.run(
+      warped_template, science, science_source_catalog)
+
+For source detection a similar pattern works:
+
+.. code-block:: python
+
+   from lsst.ip.diffim import DetectAndMeasureTask
+
+   ...
+   detect_task = DetectAndMeasureTask()
+
+   detect_and_measure = detect_and_measure_task.run(
+      science, subtraction.matchedTemplate, subtraction.difference)
+
 
 .. _lsst.ip.diffim-contributing:
 
@@ -61,7 +113,7 @@ Configurations
 
 .. lsst-configs::
    :root: lsst.ip.diffim
-   :toctree: configs
+   :toctree: config
 
 .. _lsst.ip.diffim-pyapi: