Merge pull request #1082 from spacetelescope/DR-user-guide-update-2

Added several more images and updates for build context.

documentation/crds_users_guide/source/command_line_tools.rst

@@ -210,8 +210,10 @@ New Context
 ...........
 
 crds.bestrefs always computes best references with respect to a context which
-can be explicitly specified with the `--new-context` parameter.  If `--new-context`
-is not specified, the default latest context is determined by consulting
+can be explicitly specified with the `--new-context` parameter.  For JWST, if `--new-context`
+is not specified, the default build context is determined by checking the CRDS Server to find the
+appropriate context for the Calibration Software that a user has locally installed.
+In the case of HST or Roman, the default latest context is determined by consulting
 the CRDS server or looking in the local cache.
 
 ...........
@@ -809,7 +811,7 @@ explained above:
   .. code-block:: bash
 
       $ crds list --cat jwst_nirspec_dark_0036.fits
-      CRDS - INFO - Symbolic context 'jwst-latest' resolves to 'jwst_0167.pmap'
+      CRDS - INFO - Symbolic context 'jwst-build' resolves to 'jwst_0167.pmap'
       File:  '/grp/crds/jwst/references/jwst/jwst_nirspec_dark_0036.fits'
       {'A1_COL_C': '8.9600000e+002',
       'A1_CONF1': '2.1846000e+004',
@@ -930,7 +932,7 @@ Sometimes it's desirable to know the individual exposures CRDS associates with a
 
   .. code-block:: bash
 
-      $ python m crds.list --latest-context
+      $ python m crds.list --build-context
       jwst_0204.pmap 
 
 lists the context which has been *commanded* as default on the CRDS server.
@@ -974,7 +976,7 @@ contexts:
       jwst_0208.pmap
       jwst_0209.pmap
       
-      $ crds list --resolve-contexts  --contexts jwst-miri-dark-latest
+      $ crds list --resolve-contexts  --contexts jwst-miri-dark-build
       jwst_miri_dark_0012.rmap
       
       $ crds list --resolve-contexts --contexts jwst-niriss-superbias-2016-01-01T00:00:00

documentation/crds_users_guide/source/library_use.rst

@@ -106,7 +106,8 @@ reference file paths:
                       
           context :   The name of the pipeline context mapping which should be
                   used to define best reference lookup rules,  or None.  If 
-                  `context` is None,  use the latest pipeline mapping.
+                  `context` is None,  use the latest pipeline mapping. For JWST,
+                  this is the build context mapping.
                   
                   str
                   
@@ -147,7 +148,7 @@ reference type:
         filling in appropriate reference type keywords.
     
         Define best references using either .pmap `context` or the default
-        CRDS latest context if context=None.
+        CRDS context if context=None.
     
         If `reftypes` is defined, assign bestrefs to only the listed
         reftypes, otherwise assign all reftypes.
@@ -181,15 +182,20 @@ crds.get_default_context()
 ..........................
 
 `get_default_context()` returns the name of the pipeline mapping which is 
-currently the Latest Context
+currently the Build Context in the case of JWST based on the version of the locally installed
+Calibration code, while it returns the Latest Context for HST and Roman from the Crds Server or the local cache.
 !!!!!!!!!!!!!!!!!!!
 
-*Latest Context* is the .pmap which is nominally in use by the pipeline.
-While it's common to make new files the latest as each context is added, it's
+For HST and Roman, *Latest Context* is the .pmap which is nominally in use by the pipeline. For JWST, see below.
+While it's common to make new files become the *Latest* as each context is added, it's
 possible for the *Latest Context* to lag behind the *Edit Context* when
-new files are being added but need additional testing in OPS. Deriving
-from the *Latest Context* is a crude kind of reversion since CRDS
-effectively branches around any existing subsequent contexts. use.
+new files are being added but need additional testing in OPS, and the *Latest Context* when the
+new files are confirmed. Deriving from the *Latest Context* is a crude kind of reversion since CRDS
+effectively branches around any existing subsequent contexts.
+
+*Build Context* applies to JWST, and is the .pmap which corresponds to the most recently installed
+JWST DMS Install and JWST Calibration code. It is guaranteed to work with that delivered code, and stays consistent
+after new reference files are delivered.
 
 The default context defines the matching rules used to determine best 
 reference files for a given set of parameters:

documentation/crds_users_guide/source/pipeline_management.rst

@@ -46,7 +46,7 @@ Set Context
 This section describes the website page used by operators to update the default
 CRDS context.
 
-*Set Context* enables setting the latest, edit, and versions contexts.
+*Set Context* enables setting the build, latest, edit, and versions contexts.
 
 .. figure:: images/web_set_context.png
    :scale: 50 %
@@ -55,7 +55,7 @@ CRDS context.
 CRDS enables contexts to be distributed before their adoption as the pipeline
 default.  Set Context is used to select the default pipeline (latest)
 context.
-   
+
 Setting the latest context changes state on the CRDS server which must be
 subsequently sync'ed to remote pipelines and users.
 
@@ -68,6 +68,23 @@ submissions.
 Setting the *versions* context defines the context used to locate the SYSTEM
 CALVER reference file used to define calibration software component versions.
 
+Selecting the *build* context for the Context Type changes the menu that you can use:
+
+.. figure:: images/web_set_build_context.png
+   :scale: 50 %
+   :alt: set build context inputs
+
+It adds a CAL_VER option that allows the user to set a pre-existing Cal Version, or a custom one
+that a user inputs.
+
+.. figure:: images/web_set_build_drop.png
+   :scale: 50 %
+   :alt: drop for build context inputs
+
+Selecting the checkbox for Update Home Page Banner / Pipeline Build Context will update the
+build context displayed in the front page banner if the context being set is newer then the
+existing banner context.
+
 Sync Pipeline CRDS Cache
 ++++++++++++++++++++++++
 

documentation/crds_users_guide/source/web_services.rst

@@ -75,7 +75,10 @@ when the cache is synchronized.  Since this value is inapplicable if a pipeline
 is run in "remote" mode computing best references on the CRDS Server, the
 generally preferred value is from `get_default_context()` since it always
 reflects the intended latest context regardless of the pipeline's CRDS
-mode.   
+mode. For JWST, get_default_context() retrieves the "build" context associated
+with the version of JWST pipeline calibration software installed locally,
+which may or may not differ from the "latest" context.
+This ensures compatibility between reference files and calibration software.
 
 The actual default context for a pipeline can be obtained as follows:
 

documentation/crds_users_guide/source/web_site_use.rst

@@ -27,8 +27,23 @@ For HST
    :alt: hst home page of CRDS website
 
 
+
+<--Applicable only to JWST and RST
+
 Build Context Banner
 ----------------------
+The Build Context Banner displays the CRDS Context that was delivered with a DMS build, and
+is guaranteed to work with that build. It will be the latest context when a DMS build is installed,
+but will not be the most current after references get delivered and the latest context is updated.
+
+Clicking on the `build contexts` link will bring up a table that displays the JWST Calibration Code Version that was
+available when a particular context was delivered.
+
+.. figure:: images/web_context_build_table.png
+   :scale: 50 %
+   :alt: Build CRDS contexts
+
+-->
 
 Latest References
 ----------------------
@@ -83,11 +98,7 @@ Clicking on the `all contexts` link will bring up every context that has ever be
 <--Applicable only to JWST and RST
 
 Clicking on the `build contexts` link will bring up a table that displays the JWST Calibration Code Version that was
-available when a particular context was delivered.
-
-.. figure:: images/web_context_build_table.png
-   :scale: 50 %
-   :alt: Build CRDS contexts
+available when a particular context was delivered, just as it did in the banner.
 
 Clicking a `Cal Ver` link will take you to the github release of that JWST Calibration version: