gmxapi-79 Safe management of session working directories

Document proposed user interface for filesystem artifacts.

src/gmx/context.py

@@ -286,10 +286,20 @@ class ParallelArrayContext(object):
         ...    # rank = session.rank
         ...    # The local context object knows where it fits in the global array.
         ...    rank = context.rank
-        ...    output_path = os.path.join(context.workdir_list[rank], 'traj.trr')
-        ...    assert(os.path.exists(output_path))
-        ...    print('Worker {} produced {}'.format(rank, output_path))
+        ...    output = work[0]['traj.trr']
         ...
+        >>> output_path = str(output.extract())
+        >>> assert(os.path.exists(output_path))
+
+    When the session is created to run the workflow, a uniquely named directory is created in the filesystem to be the
+    session's working directory. This directory name is available in the attribute `context.path`. Each
+    operation on each rank has its own subdirectory. In the example above, the directory for MD artifacts for each of
+    the two ranks used can be accessed through `work.path[0]` and `work.path[1]`. Artifacts in each path can be accessed
+    as dictionary keys. E.g. `work.path[0]['traj.trr']`.
+
+    Note that these attributes are proxy objects that may not exist at the time they are referenced with this syntax.
+    To force the artifacts to be made available locally, use the `extract` method. The string representation of the
+    returned object is a valid local absolute filename.
 
     Implementation notes: