Documentation

README.md

@@ -4,3 +4,21 @@
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://JoshuaBillson.github.io/LandsatExplorer.jl/dev/)
 [![Build Status](https://github.com/JoshuaBillson/LandsatExplorer.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/JoshuaBillson/LandsatExplorer.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/JoshuaBillson/LandsatExplorer.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/JoshuaBillson/LandsatExplorer.jl)
+
+[LandsatExplorer](https://github.com/JoshuaBillson/LandsatExplorer.jl) is a pure Julia package for querying and downloading Landsat data from the [USGS Earth Explorer](https://earthexplorer.usgs.gov/) ecosystem.
+
+# Installation
+
+To install this package, start the Julia REPL and open the package manager by typing `]`.
+You can then install `LandsatExplorer` from the official Julia repository like so:
+
+```
+(@v1.9) pkg> add LandsatExplorer
+```
+
+# Authentication
+
+`LandsatExplorer` needs access to your USGS Earth Explorer credentials in order to query and download
+data. These are passed in via the environment variables `LANDSAT_EXPLORER_USER` and 
+`LANDSAT_EXPLORER_PASS`. You can set them manually each time you run your program by calling 
+`authenticate("my_username", "my_password")`, or you can set them once in your `startup.jl` configuration.

docs/src/index.md

@@ -4,11 +4,32 @@ CurrentModule = LandsatExplorer
 
 # LandsatExplorer
 
-Documentation for [LandsatExplorer](https://github.com/JoshuaBillson/LandsatExplorer.jl).
+[LandsatExplorer](https://github.com/JoshuaBillson/LandsatExplorer.jl) is a pure Julia package for querying and downloading Landsat data from the [USGS Earth Explorer](https://earthexplorer.usgs.gov/) ecosystem.
+
+# Installation
+
+To install this package, start the Julia REPL and open the package manager by typing `]`.
+You can then install `LandsatExplorer` from the official Julia repository like so:
+
+```
+(@v1.9) pkg> add LandsatExplorer
+```
+
+# Authentication
+
+`LandsatExplorer` needs access to your USGS Earth Explorer credentials in order to query and download
+data. These are passed in via the environment variables `LANDSAT_EXPLORER_USER` and 
+`LANDSAT_EXPLORER_PASS`. You can set them manually each time you run your program by calling 
+`authenticate("my_username", "my_password")`, or you can set them once in your `startup.jl` configuration.
+
+# Index
 
 ```@index
 ```
 
+# API
+
 ```@autodocs
 Modules = [LandsatExplorer]
+Private = false
 ```

src/LandsatExplorer.jl

@@ -10,6 +10,23 @@ include("utils.jl")
 include("api.jl")
 include("download.jl")
 
+"""
+    authenticate(username, password)
+
+Authenticate with your USGS Earth Explorer credentials.
+
+Sets the environment variables `LANDSAT_EXPLORER_USER` and `LANDSAT_EXPLORER_PASS`, which will
+be used to authenticate future requests.
+
+# Parameters
+- `username`: Your USGS Earth Explorer username.
+- `password`: Your USGS Earth Explorer password.
+
+# Example
+```julia
+authenticate("my_username", "my_password")
+```
+"""
 function authenticate(username, password)
     ENV["LANDSAT_EXPLORER_USER"] = username
     ENV["LANDSAT_EXPLORER_PASS"] = password

src/api.jl

@@ -117,7 +117,7 @@ function get_entity_id(scene)
     end
 end
 
-"""Authenticate with the m2m API and return an access token"""
+# Authenticate with the m2m API and return an access token
 function api_authenticate()	
     login_url = "https://m2m.cr.usgs.gov/api/api/json/stable/login"
     username = get(ENV, "LANDSAT_EXPLORER_USER", "invalid")
@@ -130,7 +130,7 @@ function api_authenticate()
     return token
 end
 
-"""Send a get request to the m2m API"""
+# Send a get request to the m2m API
 function api_request(endpoint, params, token)
     payload = JSON.json(params)
     url = "https://m2m.cr.usgs.gov/api/api/json/stable/$endpoint"
@@ -139,7 +139,7 @@ function api_request(endpoint, params, token)
     return r.body |> String |> JSON.parse
 end
 
-"""Filter by acquisition date"""
+# Filter by acquisition date
 function acquisition_filter(dates::Tuple{DateTime,DateTime})
     return OrderedDict(
         "start" => Dates.format(dates[1], "yyyy-mm-dd"),
@@ -151,7 +151,7 @@ function acquisition_filter(::Nothing)
     return nothing
 end
 
-"""Filter by geographic location"""
+# Filter by geographic location
 function spatial_filter(geom::BoundingBox)
     return OrderedDict(
         "filterType" => "mbr",
@@ -189,7 +189,7 @@ function spatial_filter(::Nothing)
     return nothing
 end
 
-"""Filter by cloud coverage"""
+# Filter by cloud coverage
 function cloud_filter(cloud_cover::Integer)
     return OrderedDict(
         "min" => 0, 

src/download.jl

@@ -53,7 +53,7 @@ function download_scene(scene, dir=pwd(); log_progress=true, unpack=false)
     end
 end
 
-"""Generate authentication cookies for downloading scenes"""
+# Generate authentication cookies for downloading scenes
 function authenticate_download()
     # Get CSRF Token
     auth_url = "https://ers.cr.usgs.gov/login/"
@@ -86,13 +86,17 @@ function authenticate_download()
     HTTP.COOKIEJAR.entries["ers.cr.usgs.gov"] = Dict{String, HTTP.Cookies.Cookie}()
 end
 
-"""Returns true if logged in to the download API"""
+# Returns true if logged in to the download API
 function logged_in()
     cookies = get(HTTP.COOKIEJAR.entries, "earthexplorer.usgs.gov", nothing)
     !isnothing(cookies) && "usgs.gov;/;EROS_SSO_production_secure" in keys(cookies)
 end
 
-"""Logout of earthexplorer; this is necessary to prevent authentication errors down the line"""
+"""
+    logout()
+
+Logout of Earth Explorer.
+"""
 function logout()
     HTTP.get("https://earthexplorer.usgs.gov/logout", status_exception=false)
 end

src/utils.jl

@@ -1,14 +1,14 @@
-"""Returns true if string matches format for scene id"""
+# Returns true if string matches format for scene id
 function is_scene_id(id)
     return length(id) == 40 && first(id) == 'L'
 end
 
-"""Returns true if string matches format for entity id"""
+# Returns true if string matches format for entity id
 function is_entity_id(id)
     return length(id) == 21 && first(id) == 'L'
 end
 
-"""Parse metadata from Landsat scene ID"""
+# Parse metadata from Landsat scene ID
 function parse_scene_id(scene_id)
     elements = split(scene_id, "_")
     return Dict(
@@ -24,7 +24,7 @@ function parse_scene_id(scene_id)
     )
 end
 
-"""Parse metadata from Landsat entity ID"""
+# Parse metadata from Landsat entity ID
 function parse_entity_id(entity_id)
     return Dict(
         "entity_id" => entity_id,
@@ -39,7 +39,7 @@ function parse_entity_id(entity_id)
     )
 end
 
-"""Return the dataset string for the provided satellite and processing level"""
+# Return the dataset string for the provided satellite and processing level
 function get_dataset(satellite, level)
     sensor = @match satellite begin
         "LANDSAT_5" || 5 => "tm"
@@ -51,7 +51,7 @@ function get_dataset(satellite, level)
     return "landsat_$(sensor)_c2_l$level"
 end
 
-"""Return the data id to download a scene belonging to the given dataset"""
+# Return the data id to download a scene belonging to the given dataset
 function get_data_id(dataset)
     products = Dict(
         "landsat_tm_c2_l1"=>["5e81f14f92acf9ef", "5e83d0a0f94d7d8d", "63231219fdd8c4e5"],
@@ -65,7 +65,7 @@ function get_data_id(dataset)
     return products[dataset]
 end
 
-"""Guess the dataset string for the given identifier"""
+# Guess the dataset string for the given identifier
 function guess_dataset(identifier)
     if is_scene_id(identifier)
         metadata = parse_scene_id(identifier)