Doc

docs/basic_usage.rst

@@ -0,0 +1,79 @@
+Basic Usage
+===========
+
+
+This example shows how to query the data from a bounding box, order surface reflectance processing for full scenes without reprojection and download.
+
+Define variables and query available scenes to Usgs
+---------------------------------------------------
+
+.. code:: python
+
+    from lsru import Usgs
+    import datetime
+
+    # Define query extent
+    bbox = (3.5, 43.4, 4, 44)
+
+    # Instantiate Usgs class and login
+    usgs = Usgs()
+    usgs.login()
+
+    # Query the Usgs api to find scene intersecting with the spatio-temporal window
+    scene_list = usgs.search(collection='LANDSAT_8_C1',
+                             bbox=bbox,
+                             begin=datetime.datetime(2013,1,1),
+                             end=datetime.datetime(2016,1,1),
+                             max_results=10,
+                             max_cloud_cover=40)
+
+    # Extract Landsat scene ids for each hit from the metadata
+    scene_list = [x['displayId'] for x in scene_list]
+
+
+Place a processing order to Espa
+--------------------------------
+
+The scene list can be used to send a processing order to Espa via the Espa API. 
+
+.. code:: python
+
+    from lsru import Espa
+    from pprint import print
+
+    # Instantiate Espa class
+    espa = Espa()
+
+    # Place order (full scenes, no reprojection, sr and pixel_qa)
+    order = espa.order(scene_list=scene_list, products=['sr', 'pixel_qa'])
+    print(order.orderid)
+
+    # [email protected]'
+
+Check current orders status
+---------------------------
+
+.. code:: python
+
+    for order in espa.orders:
+        # Orders have their own class with attributes and methods
+        print('%s: %s' % (order.orderid, order.status))
+
+    # [email protected]: ordered
+    # [email protected]: complete
+    # [email protected]: complete
+    # [email protected]: complete
+    # [email protected]: complete
+
+
+Download completed orders
+-------------------------
+
+When Espa finishes pre-processing an order, its status 
+changes to ``complete``, we can then download the processed scenes.
+
+.. code:: python
+
+    for order in espa.orders:
+        if order.is_complete:
+            order.download_all_complete('/media/landsat/download/dir')

docs/example_polygon.rst

@@ -2,7 +2,7 @@ Order data using a polygon
 ==========================
 
 The following example details the steps to place a pre-processing order of scenes intersecting with a polygon. 
-Such task requires a little bit of boilerplate code since the Usgs API requires an extent and not a , but thanks to ``shapely`` and some additional utilities provided by ``lsru`` can be done with a few lines of code. 
+Such task requires a little bit of boilerplate code since the Usgs API requires an extent and not a polygon, but thanks to ``shapely`` and some additional utilities provided by ``lsru`` it can be done with a few lines of code. 
 The steps are roughly to:
 
 - Read the feature (e.g. using ``fiona`` or directly from a geojson file with ``json``)
@@ -11,7 +11,7 @@ The steps are roughly to:
 - Filter out scenes that do not intersect with the geometry
 - Place the pre-processing order to Espa
 
-To run this script, we'll need shapely, and some utils to manipulate geojson geometries provided by lsru. You may need fiona as well in case you need to read a feature from a geospatial vector file (shapefile, geopackage, etc)
+To run this script, we'll need shapely, and some utils to manipulate geojson geometries provided by ``lsru``. You may need fiona as well in case you need to read a feature from a geospatial vector file (shapefile, geopackage, etc)
 
 .. code:: python
 

docs/index.rst

@@ -12,14 +12,16 @@ It has 3 main classes:
 - ``Order`` is the interface to each individual orders placed to the espa platform; it allows retrieving order status and downloading corresponding scenes.
 
 
-``lsru`` also contain various utilities to smoothen workflows for various use cases of the module.
+``lsru`` also contains various utilities to smoothen workflows for various use cases of the module.
 
 
 
 .. toctree::
    :maxdepth: 1
    :caption: User guide
 
+   user_guide
+
 
 .. toctree::
    :maxdepth: 1
@@ -32,6 +34,7 @@ It has 3 main classes:
    :maxdepth: 1
    :caption: Examples
 
+   basic_usage
    example_polygon
 
 

docs/user_guide.rst

@@ -0,0 +1,26 @@
+User Guide
+==========
+
+Installation
+------------
+
+Activate a virtualenv (optional but preferable) and run:
+
+.. code:: sh
+
+    pip install lsru
+
+
+Setup
+-----
+
+The package requires a configuration file in which usgs credentials are written. 
+By default the file is called ``~/.lsru`` (this can be modified if you want to join 
+this configuration with the configuration of another project) and has the following structure.
+
+::
+
+    [usgs]
+    username=your_usgs_username
+    password=your_very_secure_password
+