update docs

Author: gbrammer

CHANGES.rst

@@ -8,6 +8,11 @@ New Tools and Services
 Service fixes and enhancements
 ------------------------------
 
+eso
+^^^
+
+- Add option to retrieve_data from an earlier archive query [#1614]
+
 sdss
 ^^^^
 

astroquery/eso/core.py

@@ -629,8 +629,8 @@ def _download_file(self, url, local_filepath, **kwargs):
         return resp
 
     def retrieve_data(self, datasets, continuation=False, destination=None,
-                      with_calib='none', request_all_objects=False, unzip=True,
-                      request_id=None):
+                      with_calib='none', request_all_objects=False,
+                      unzip=True, request_id=None):
         """
         Retrieve a list of datasets form the ESO archive.
 
@@ -660,7 +660,7 @@ def retrieve_data(self, datasets, continuation=False, destination=None,
             default.
         request_id : str, int
             Retrieve from an existing request number rather than sending a new
-            query, with the `request_id` from the URL in the email sent from
+            query, with the identifier from the URL in the email sent from
             the archive from the earlier request as in:
 
                 https://dataportal.eso.org/rh/requests/[USERNAME]/[request_id]

docs/eso/eso.rst

@@ -348,6 +348,24 @@ a ``location`` keyword in the call to :meth:`~astroquery.eso.EsoClass.retrieve_d
 In all cases, if a requested dataset is already found,
 it is not downloaded again from the archive.
 
+By default, calling ``eso.retrieve_data`` submits a new archive request
+through the web form to stage and download the requested ``datasets``. If you
+would like to download datasets from an existing request, either submitted
+through the functions here or externally, call ``retrieve_data`` with the
+``request_id`` option:
+
+.. code-block:: python
+
+    >>> data_files = eso.retrieve_data(table['DP.ID'][:2], request_id=999999)
+
+The ``request_id`` can be found in the automatic email sent by the archive after
+staging the initial request, i.e., https://dataportal.eso.org/rh/requests/[USERNAME]/{request_id}. A summary of your available requests is shown at https://dataportal.eso.org/rh/requests/[USERNAME]/recentRequests.  
+
+Note: The function does check that the specified retrieval URL based on
+``request_id`` is valid and then that the datasets indicated there are
+consistent with the user-specified ``datasets``, but there is currently no
+reverse checking that the specified ``datasets`` are provided in
+``request_id``.
 
 Reference/API
 =============