spacetelescope · melanieclarke · Sep 18, 2024 · Sep 16, 2024 · Sep 16, 2024 · Sep 16, 2024
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -80,6 +80,9 @@ documentation
 
 - Add changelog to documentation. [#8716]
 
+- Updated description of association keyword `expname`: including path information
+  in addition to the filename is discouraged, but allowed. [#8789]
+
 emicorr
 -------
 

diff --git a/docs/jwst/associations/association_api.rst b/docs/jwst/associations/association_api.rst
@@ -1,3 +1,4 @@
 .. _asn-full-api:
 
 .. automodapi:: jwst.associations
+   :skip: main
diff --git a/docs/jwst/associations/level2_asn_technical.rst b/docs/jwst/associations/level2_asn_technical.rst
@@ -133,10 +133,14 @@ members *required*
 association. Each member has the following keywords.
 
 expname *required*
-  The exposure file name.  This must be a filename only, with no path.  This
-  file must be in the same directory as the association file, so path is not
-  needed.  If path data is included, an exception is raised when loading the
-  association file.
+  The exposure file name.
+
+  It is recommended that this value be set to a filename only,
+  with no path. In this case, the file must be in the same directory as the
+  association file, so the path is not needed.  If valid absolute or relative
+  path data is included, the input file is still found and used by the pipeline,
+  but a warning is raised: the association file in this case may be less portable
+  than if the path data is not included.
 
 exptype *required*
   Type of information represented by the exposure. Possible

diff --git a/docs/jwst/associations/level3_asn_technical.rst b/docs/jwst/associations/level3_asn_technical.rst
@@ -135,7 +135,14 @@ members *required*
 association. Each member has the following keywords.
 
 expname *required*
-  The exposure file name
+  The exposure file name.
+
+  It is recommended that this value be set to a filename only,
+  with no path. In this case, the file must be in the same directory as the
+  association file, so the path is not needed.  If valid absolute or relative
+  path data is included, the input file is still found and used by the pipeline,
+  but a warning is raised: the association file in this case may be less portable
+  than if the path data is not included.
 
 exptype *required*
   Type of information represented by the exposure. Possible values are

diff --git a/docs/jwst/associations/overview.rst b/docs/jwst/associations/overview.rst
@@ -84,13 +84,16 @@ Usage
 
 Users should not need to run the generator. Instead, it is expected that one
 edits an already existing association that accompanies the user's JWST data.
-Care should be taken if editing an association file.  Keep in mind all input
-files listed in the association file are in the same directory as the
-association file and no path information can be put in ``expname``, only the
-file name.  Or, if need be, an association can be created based on the existing
-:ref:`Stage 2 <asn-level2-example>` or :ref:`Stage 3 <asn-level3-example>` examples.
-If, however, the user *does* need to run the generator, :ref:`Association Generator
-<design-generator>` documentation will be helpful.
+
+Care should be taken if editing an association file.  Keep in mind that generally
+all input files listed in the association files are assumed to be in the same
+directory as the association file and no path information is put in ``expname``.
+
+If need be, an association can be created based on the existing
+:ref:`Stage 2 <asn-level2-example>` or :ref:`Stage 3 <asn-level3-example>` examples,
+or using the command line tool :ref:`asn-from-list`.
+If, however, the user *does* need to run the generator, the :ref:`Association Generator
+<design-generator>` description and :ref:`asn-generate` documentation will be helpful.
 
 Once an association is in-hand, one can pass it as input to a pipeline
 routine. For example::

diff --git a/jwst/associations/asn_from_list.py b/jwst/associations/asn_from_list.py
@@ -9,7 +9,7 @@
 
 
 def asn_from_list(items, rule=DMS_Level3_Base, **kwargs):
-    """Creat an association from a list
+    """Create an association from a list
 
     Parameters
     ----------
@@ -32,7 +32,7 @@ def asn_from_list(items, rule=DMS_Level3_Base, **kwargs):
     -----
     This is a lower-level tool for artificially creating
     an association. As such, the association created may not be valid.
-    It is presume the user knows what they are doing.
+    It is presumed the user knows what they are doing.
     """
 
     asn = rule()

diff --git a/jwst/associations/association.py b/jwst/associations/association.py
@@ -209,8 +209,8 @@ def validate(cls, asn):
                 fpath, fname = os.path.split(member["expname"])
                 if len(fpath) > 0:
                     err_str = "Input association file contains path information;"
-                    err_str += "  note that this can complicate usage and/or sharing"
-                    err_str += "  of such files."
+                    err_str += " note that this can complicate usage and/or sharing"
+                    err_str += " of such files."
                     logger.debug(err_str)
                     warnings.warn(err_str, UserWarning)
         return True
-Original file line number
+Diff line change
@@ Expand Up / @@ -80,6 +80,9 @@ documentation @@
     - Add changelog to documentation. [#8716]
+    - Updated description of association keyword `expname`: including path information
+      in addition to the filename is discouraged, but allowed. [#8789]
     emicorr
     -------
@@ Expand Down @@