major revision of the RS user manual.

recipe_system/doc/rs_UsersManual/_static/css/custom_code.css

@@ -0,0 +1,16 @@
+
+/* , a .rst-content tt, a .rst-content code */
+
+.rst-content code.xref {
+    background-color: transparent;
+    border: solid 1px transparent;
+    color: #2980B9;
+    padding: 0px 0px;
+    font-size: 80%;
+    }
+
+.rst-content code.xref:hover {
+    /* border: solid 1px #e1e4e5; */
+    text-decoration: underline;
+    }
+

recipe_system/doc/rs_UsersManual/_static/fonts.css

@@ -0,0 +1,36 @@
+.red {
+  color: red;
+}
+
+.blue {
+  color: blue;
+}
+
+.green {
+  color: green;
+}
+
+.yellow {
+  color: yellow;
+}
+
+.gray {
+  color: gray;
+}
+
+.lightgray {
+  color: lightgray;
+}
+
+.small {
+  font-size: 80%;
+}
+
+.large {
+  font-size: 120%;
+}
+
+.bolditalic {
+  font-weight: bold;
+  font-style: italic;
+}

recipe_system/doc/rs_UsersManual/_static/rtd_theme_overrides.css

@@ -0,0 +1,20 @@
+/* override RTD table width restrictions */
+
+@media screen and (min-width: 767px) {
+
+  .wy-table-responsive table td, .wy-table-responsive table th {
+      /* !important prevents the common CSS stylesheets from 
+         overriding this as on RTD the are loaded after this stylesheet */
+      white-space: normal !important;
+  } 
+
+  .wy-table-responsive {
+      /* margin-bottom: 24px; */ 
+      /* max-width: 100%; */
+      overflow: visible !important;
+  }
+
+  .wy-nav-content {
+      max-width: 1200px !important;
+  }
+}

recipe_system/doc/rs_UsersManual/_static/todo-styles.css

@@ -5,3 +5,4 @@ border-left: 2px solid red;
 border-right: 2px solid red;
 background-color: #ff6347
 }
+

recipe_system/doc/rs_UsersManual/ack.rst

@@ -1,9 +1,13 @@
-6. Acknowledgments
-==================
-The Gemini Observatory is operated by the Association of Universities for 
-Research in Astronomy (AURA), Inc., under a cooperative agreement with the NSF on 
-behalf of the Gemini partnership: the National Science Foundation 
-(United States), the Science and Technology Facilities Council (United Kingdom), 
-the National Research Council (Canada), CONICYT (Chile), the Australian 
-Research Council (Australia), Ministerio da Ciencia e Tecnologia (Brazil), 
-and Ministerio de Ciencia, Tecnologia e Innovacion Productiva (Argentina).
+.. ack.rst
+
+***************
+Acknowledgments
+***************
+
+The Gemini Observatory is operated by the Association of Universities for
+Research in Astronomy, Inc., under a cooperative agreement with the NSF on
+behalf of the Gemini partnership: the National Science Foundation
+(United States), the National Research Council (Canada), CONICYT (Chile),
+Ministerio de Ciencia, Tecnología e Innovación Productiva (Argentina),
+Ministério da Ciência, Tecnologia e Inovação (Brazil), and Korea Astronomy
+and Space Science Institute (Republic of Korea).

recipe_system/doc/rs_UsersManual/appendices/full_api_example.rst

@@ -0,0 +1,95 @@
+.. full_api_example.rst
+
+.. _api_example:
+
+****************
+Full API Example
+****************
+Here we put together several of the tools to show how it can all work, from
+beginning to end.
+
+1. Import everything we will need.
+
+   ::
+
+    >>> import glob
+
+    >>> from recipe_system.reduction.coreReduce import Reduce
+    >>> from recipe_system import cal_service
+
+    >>> from gempy.utils import logutils
+    >>> from gempy.adlibrary import dataselect
+
+2. Create the file lists.  One for the darks, one for the flats, one for the
+   science target.
+
+   ::
+
+    >>> all_files = glob.glob('../raw/*.fits')
+
+    # 20 second darks.
+    >>> expression = 'exposure_time==20'
+    >>> parsed_expr = dataselect.expr_parser(expression)
+    >>> darks20s = dataselect.select_data(all_files, ['DARK'], [], parsed_expr)
+
+    # all the flats
+    >>> flats = dataselect.select_data(all_files, ['FLAT'])
+
+    # the science data
+    >>> expression = 'object=="SN2014J"'
+    >>> parsed_expr = dataselect.expr_parser(expression)
+    >>> target = dataselect.select_data(all_files, expression=parsed_expr)
+
+3. Set up the calibration manager and database.  First, create or edit the
+   ``~/.geminidr/rsys.cfg`` to look like this:
+
+   ::
+
+    [calibs]
+    standalone = True
+    database_dir = <where_you_want_the_database_to_live>/
+
+   Then configure and initialize the database, and activate the service:
+
+   ::
+
+    >>> caldb = cal_service.CalibrationService()
+    >>> caldb.config()
+    >>> caldb.init()
+    >>> cal_service.set_calservice()
+
+4. Set up the logger.
+
+   ::
+
+    >>> logutils.config(file_name='example.log')
+
+5. Reduce the darks and add the master dark to the calibration database.
+
+   ::
+
+    >>> reduce_darks = Reduce()
+    >>> reduce_darks.files.extend(darks20s)
+    >>> reduce_darks.runr()
+
+    >>> caldb.add_cal(reduce_darks.output_filenames[0])
+
+6. Reduce the flats and add the master flats to the calibration database.
+
+   ::
+
+    >>> reduce_flats = Reduce()
+    >>> reduce_flats.files.extend(flats)
+    >>> reduce_flats.runr()
+
+    >>> caldb.add_cal(reduce_flats.output_filenames[0])
+
+7. Reduce the science target, with some input parameter override.
+
+   ::
+
+    >>> reduce_target = Reduce()
+    >>> reduce_target.files.extend(target)
+    >>> reduce_target.uparms.append(('skyCorrect:scale', False))
+    >>> reduce_target.runr()
+

recipe_system/doc/rs_UsersManual/appendices/full_commandline_example.rst

@@ -0,0 +1,53 @@
+.. full_commandline_example.rst
+
+.. _commandline_example:
+
+*************************
+Full Command Line Example
+*************************
+Here we put together several of the tools to show how it can all work, from
+beginning to end.
+
+1. First create the lists.  One for the darks, one for the flats, and one for
+   the science target.
+
+   ::
+
+    $ dataselect ../raw/*.fits --tags DARK --expr='exposure_time==20' -o darks20s.lis
+    $ dataselect ../raw/*.fits --tags FLAT -o flats.lis
+    $ dataselect ../raw/*.fits --expr='object=="SN2014J"' -o target.lis
+
+2. Set the calibration manager and database.  First, create or edit the
+   ``~/.geminidr/rsys.cfg`` to look like this:
+
+   ::
+
+    [calibs]
+    standalone = True
+    database_dir = <path_to>/redux_dir/
+
+   Then initialize the calibration database.
+
+   ::
+
+    $ caldb init
+
+3. Reduce the darks and add the master dark to the calibration database.
+
+   ::
+
+    $ reduce @darks20s.lis
+    $ caldb add N20160102S0423_dark.fits
+
+4. Reduce the flats and add the master flat to the calibration database.
+
+   ::
+
+    $ reduce @flats.lis
+    $ caldb add N20160102S0373_flat.fits
+
+5. Reduce the science target, with some input parameter override.
+
+   ::
+
+    $ reduce @target.lis -p skyCorrect:scale=False

recipe_system/doc/rs_UsersManual/appendices/glossary.rst

@@ -7,18 +7,13 @@ Glossary
 
 .. glossary::
 
-  adcc
-
-      Automatated Data Communication Center. Provides  HTTP 
-      service for moinitoring QA metrics produced during pipeline operations. 
-      This is run externally to ``reduce.`` Users need not know about or invoke 
-      the ``adcc`` for ``reduce`` operations.
-
   astrodata
 
-      Part of the DRAGONS package that defines the abstraction 
-      layer for observational datasets. This abstraction layer is used
-      extensively by the Recipe System to effect correct processing.
+      Package distributed with the DRAGONS meta-package. ``astrodata`` is used
+      to open datasets and provide an uniform interface to the data and the
+      metadata (eg. headers) regardless of whether the file on disk is a FITS
+      file or some other format, whether it is a GMOS file or NIRI file.  The
+      Recipe System relies critically on ``astrodata``.
 
   AstroData
 
@@ -27,60 +22,51 @@ Glossary
       developers will interact with at a programmatic level.
 
   descriptor
-      Is a method on an ``AstroData`` instance. A descriptor represents a 
-      high-level metadata name and provides access to essential metadata
-      through a uniform, instrument-agnostic interface to the FITS headers.
-      E.g., ``ad.gain()``
+      A descriptor is a high-level access to essential dataset metadata
+      (eg. headers) through a uniform, instrument-independent interface.
+      E.g., ``ad.gain()``.  A descriptor is a method on an ``AstroData``
+      instance.
 
   DRAGONS
       Data Reduction for Astronomy from Gemini Observatory North and South.
 
       A suite of packages comprising ``astrodata``, ``gemini_instruments``, the
-      ``recipe_system`` and ``gempy``, all of which provide the full functionality
-      needed to run recipe pipelines on observational datasets. DRAGONS can be
-      referred to as a framework.
+      ``recipe_system``, ``geminidr``, and ``gempy``, which together provide
+      the full functionality needed to run recipe pipelines on observational
+      datasets. DRAGONS can be referred to as a framework.
 
   gempy
-      A DRAGONS package comprising gemini specific functional utilities.
+      A DRAGONS package comprising various functional utilities, some generic,
+      some Gemini-specific.
 
   primitive
-      A function defined within a data reduction instrument package (a "dr" package) 
-      that performs actual work on the passed dataset. Primitives observe controlled 
-      interfaces in support of re-use of primitives and recipes for different types 
-      of data, when possible. For example, all primitives called ``flatCorrect`` 
-      must apply the flat field correction appropriate for the data’s current 
-      astrodata tag set, and must have the same set of input parameters. This is a 
+      A function defined within a data reduction instrument package that
+      performs actual work on a dataset. Primitives observe controlled
+      interfaces in support of re-use of primitives and recipes for different
+      types of data, when possible. For example, all primitives called
+      ``flatCorrect``  must apply the flat field correction appropriate for
+      the data, and must have the same set of input parameters. This is a
       Gemini Coding Standard; it is not enforced by the Recipe System.
 
   recipe
-      A function defined in a recipe library (module), which defines a sequence
-      of function calls. A recipe is a simple python function that recieves an 
-      instance of the appropriate primitive class and calls the available methods 
-      that are to be done for a given recipe function. A **recipe** is the 
-      high-level pipeline definition. Users can pass recipe names directly to 
-      ``reduce.`` Essentially, a recipe is a pipeline.
+      A function defined in a recipe library (module) which defines a sequence
+      of calls to primitives. A recipe is a simple python function that receives
+      an instance of the appropriate primitive class (primitive set) and
+      executes the primitive sequence defined in the recipe function.  Users
+      can pass recipe names directly to ``reduce.``
 
   Recipe System
-      The DRAGONS framework that accommodates defined recipes and primitives 
-      classes. The Recipe System defines a set of classes that exploit attributes 
-      on an astrodata instance of a dataset to locate recipes and primitives 
-      appropriate to that dataset.
+      The DRAGONS framework that automates the selection and execution of
+      recipes and primitives. The Recipe System defines a set of classes that
+      uses attributes on an astrodata instance to locate recipes and primitives
+      appropriate to the dataset.
 
   reduce
-      The command line interface to the Recipe System and associated
-      recipes/pipelines.
+      The command line interface to the Recipe System.
 
   tags [or tagset]
-      Represent a data classification. A dataset will be classified by a number
-      of tags that describe both the data and its processing state. For example,
-      a typical unprocessed GMOS image taken at Gemini-South would have the 
-      following tagset::
-
-       set(['RAW', 'GMOS', 'GEMINI', 'SIDEREAL', 'UNPREPARED', 'IMAGE', 'SOUTH'])
-
-      Instrument packages define *tagsets*, which are sets of string literals 
-      that describe and the kind of observational data that the package, 
-      primitive, or library has been defined to accommodate and process. 
-      As an example::
+      Represents a data classification. When loaded with ``AstroData``, a
+      dataset will be classified with a number of tags that describe both the
+      data and its processing state.  The tags are defined in *astrodata
+      packages*, eg. the Gemini package is ``gemini_instruments``.
 
-       set(['GMOS', 'MOS', 'NODANDSHUFFLE')]