Expanding documentation.

README.rst

@@ -5,7 +5,8 @@ csppfetch is a Python 3 module for downloading dynamic ancillary data. It
 supports downloading individual files needed for processing a given time step
 (and optionally maintaining a local cache as it does) as well as explicitly
 maintaining a local cache. It uses fcntl.lockf to allow multiple copies to
-safely run at the same time.
+safely run at the same time.  It implements the 
+`CSPP Geo ancillary download behavior guidelines <https://docs.google.com/document/d/1phQRbELddAl4AG2EdAvzlJOKdYD0HRu-TpD3fj7J1rA/edit?pli=1>`_.
 
 Requires Python 3.6 or later.
 
@@ -13,6 +14,8 @@ Requires Python 3.6 or later.
 Example
 -------
 
+Setup
+
 >>> import csppfetch
 >>> import datetime
 >>> sst_filename = "avhrr-only-v2.%Y%m%d_preliminary.nc"
@@ -25,26 +28,45 @@ Example
 ...     period = datetime.timedelta(hours=24),
 ...     epoch_start = datetime.datetime(2010,1,1,3,0,0)
 ...     )
->>> import tempfile, os
->>> #
->>> # Download files needed to process a scan at 2019-5-27 12:00:00
->>> with tempfile.TemporaryDirectory() as example_dir:
-...     sst.download_for_time(datetime.datetime(2019,5,27, 12,0,0), example_dir)
+
+(Some imports for these examples, not required for module use!)
+ 
+>>> from tempfile import TemporaryDirectory
+>>> import os
+
+
+Download files needed to process a scan at 2019-5-27 12:00:00:
+
+>>> scan_time = datetime.datetime(2019,5,27, 12,0,0)
+>>> with TemporaryDirectory() as example_dir:
+...     sst.download_for_time(scan_time, example_dir)
 ...     os.path.exists(example_dir+"/avhrr-only-v2.20190527_preliminary.nc")
 True
->>> #
->>> # Download files last 7 days of files
->>> with tempfile.TemporaryDirectory() as example_dir:
+
+Download last 7 days of files
+
+>>> with TemporaryDirectory() as example_dir:
 ...     sst.mirror(example_dir)
+...     len(os.listdir(example_dir)) > 3
+True
+
+(The test is ">3" because due to vaguaries of mirroring, we are likely to get fewer, sometimes many fewer, than the ideal 6 or 7.)
 
 
 
 Usage
 -----
 
-``csppfetch.Downloader.download_for_time`` implements the `CSPP Geo ancillary
-download behavior guidelines
-<https://docs.google.com/document/d/1phQRbELddAl4AG2EdAvzlJOKdYD0HRu-TpD3fj7J1rA/edit?pli=1>`_.
+See ``import csppfetch; help(csppfetch.Downloader.__init__)`` for details on
+the arguments to Downloader.
+
+TODO: Expand on WHY you'd use various options.
+
+
+
+
+``csppfetch.Downloader.download_for_time`` implements the 
+`CSPP Geo ancillary download behavior guidelines <https://docs.google.com/document/d/1phQRbELddAl4AG2EdAvzlJOKdYD0HRu-TpD3fj7J1rA/edit?pli=1>`_.
 It defaults to to abandoning a download after 30 seconds, will retry 3
 failures, and waits 20 seconds between retry attempts. These can be overridden
 with the environment variables ``<prefix>_TIMEOUT``, ``<prefix>_RETRIES``, and