Clarify that temporal and bbox args must be tuples in docstrings, fix docstring formatting

binder/environment-dev.yml

@@ -10,6 +10,16 @@ dependencies:
   - ipyleaflet>=0.13
   - h5netcdf>=0.11
   - cartopy
+
+  - mkdocs>=1.2
+  - mkdocs-material>=7.1,<9.0
+  - markdown-include>=0.6
+  - mkdocstrings>=0.19.0
+  - mkdocstrings-python
+  - mkdocs-jupyter>=0.19.0
+  - pymdown-extensions>=9.2
+
   - pip
   - pip:
       - poetry
+      - markdown-callouts>=0.2.0

earthaccess/api.py

@@ -13,7 +13,7 @@
 from .utils import _validation as validate
 
 
-def _normalize_location(location: Union[str, None]) -> Union[str, None]:
+def _normalize_location(location: Optional[str]) -> Optional[str]:
     """Handle user-provided `daac` and `provider` values
 
     These values must have a capital letter as the first character
@@ -31,32 +31,29 @@ def _normalize_location(location: Union[str, None]) -> Union[str, None]:
 def search_datasets(
     count: int = -1, **kwargs: Any
 ) -> List[earthaccess.results.DataCollection]:
-    """Search datasets using NASA's CMR
+    """Search datasets using NASA's CMR.
 
     [https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html](https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html)
 
     Parameters:
-
-        count (Integer): Number of records to get, -1 = all
-        kwargs (Dict): arguments to CMR:
+        count: Number of records to get, -1 = all
+        kwargs (Dict):
+            arguments to CMR:
 
             * **keyword**: case insensitive and support wild cards ? and *,
-
             * **short_name**: e.g. ATL08
-
             * **doi**: DOI for a dataset
-
             * **daac**: e.g. NSIDC or PODAAC
-
             * **provider**: particular to each DAAC, e.g. POCLOUD, LPDAAC etc.
+            * **temporal**: a tuple representing temporal bounds in the form
+              `("yyyy-mm-dd", "yyyy-mm-dd")`
+            * **bounding_box**: a tuple representing spatial bounds in the form
+              `(lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)`
 
-            * **temporal**: ("yyyy-mm-dd", "yyyy-mm-dd")
-
-            * **bounding_box**: (lower_left_lon, lower_left_lat ,
-                               upper_right_lon, upper_right_lat)
     Returns:
-        an list of DataCollection results that can be used to get
-        information such as concept_id, doi, etc. about a dataset.
+        a list of DataCollection results that can be used to get information about a
+            dataset, e.g. concept_id, doi, etc.
+
     Examples:
         ```python
         datasets = earthaccess.search_datasets(
@@ -89,27 +86,24 @@ def search_data(
     [https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html](https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html)
 
     Parameters:
-
-        count (Integer): Number of records to get, -1 = all
-        kwargs (Dict): arguments to CMR:
+        count: Number of records to get, -1 = all
+        kwargs (Dict):
+            arguments to CMR:
 
             * **short_name**: dataset short name e.g. ATL08
-
             * **version**: dataset version
-
             * **doi**: DOI for a dataset
-
             * **daac**: e.g. NSIDC or PODAAC
-
             * **provider**: particular to each DAAC, e.g. POCLOUD, LPDAAC etc.
+            * **temporal**: a tuple representing temporal bounds in the form
+              `("yyyy-mm-dd", "yyyy-mm-dd")`
+            * **bounding_box**: a tuple representing spatial bounds in the form
+              `(lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)`
 
-            * **temporal**: ("yyyy-mm-dd", "yyyy-mm-dd")
-
-            * **bounding_box**: (lower_left_lon, lower_left_lat ,
-                               upper_right_lon, upper_right_lat)
     Returns:
-        Granules: a list of DataGranules that can be used to access
-          the granule files by using `download()` or `open()`.
+        a list of DataGranules that can be used to access the granule files by using
+            `download()` or `open()`.
+
     Examples:
         ```python
         datasets = earthaccess.search_data(
@@ -134,17 +128,15 @@ def login(strategy: str = "all", persist: bool = False) -> Auth:
     """Authenticate with Earthdata login (https://urs.earthdata.nasa.gov/)
 
     Parameters:
+        strategy:
+            authentication method.
 
-        strategy (String): authentication method.
-
-                "all": (default) try all methods until one works
-
-                "interactive": enter username and password.
-
-                "netrc": retrieve username and password from ~/.netrc.
+            * **"all"**: (default) try all methods until one works
+            * **"interactive"**: enter username and password.
+            * **"netrc"**: retrieve username and password from ~/.netrc.
+            * **"environment"**: retrieve username and password from `$EARTHDATA_USERNAME` and `$EARTHDATA_PASSWORD`.
+        persist: will persist credentials in a .netrc file
 
-                "environment": retrieve username and password from $EARTHDATA_USERNAME and $EARTHDATA_PASSWORD.
-        persist (Boolean): will persist credentials in a .netrc file
     Returns:
         an instance of Auth.
     """
@@ -168,7 +160,7 @@ def login(strategy: str = "all", persist: bool = False) -> Auth:
 
 def download(
     granules: Union[DataGranule, List[DataGranule], str, List[str]],
-    local_path: Union[str, None],
+    local_path: Optional[str],
     provider: Optional[str] = None,
     threads: int = 8,
 ) -> List[str]:
@@ -208,8 +200,10 @@ def open(
     hosted on S3 or HTTPS by third party libraries like xarray.
 
     Parameters:
-        granules: a list of granule instances **or** list of URLs, e.g. s3://some-granule,
-        if a list of URLs is passed we need to specify the data provider e.g. POCLOUD, NSIDC_CPRD etc.
+        granules: a list of granule instances **or** list of URLs, e.g.
+            `s3://some-granule`, if a list of URLs is passed we need to specify the data
+            provider e.g. POCLOUD, NSIDC_CPRD etc.
+
     Returns:
         a list of s3fs "file pointers" to s3 files.
     """
@@ -229,9 +223,10 @@ def get_s3_credentials(
     this is useful for missions that do not use the same endpoint as their DAACs e.g. SWOT
 
     Parameters:
-        daac (String): a DAAC short_name like NSIDC or PODAAC etc
-        provider (String: if we know the provider for the DAAC e.g. POCLOUD, LPCLOUD etc.
-        results (list[earthaccess.results.DataGranule]): List of results from search_data()
+        daac: a DAAC short_name like NSIDC or PODAAC etc
+        provider: if we know the provider for the DAAC e.g. POCLOUD, LPCLOUD etc.
+        results: List of results from search_data()
+
     Returns:
         a dictionary with S3 credentials for the DAAC or provider
     """
@@ -246,10 +241,8 @@ def get_s3_credentials(
 def collection_query() -> Type[CollectionQuery]:
     """Returns a query builder instance for NASA collections (datasets)
 
-    Parameters:
-        cloud_hosted (Boolean): initializes the query builder for cloud hosted collections.
     Returns:
-        class earthaccess.DataCollections: a query builder instance for data collections.
+        a query builder instance for data collections.
     """
     if earthaccess.__auth__.authenticated:
         query_builder = DataCollections(earthaccess.__auth__)
@@ -261,11 +254,8 @@ class earthaccess.DataCollections: a query builder instance for data collections
 def granule_query() -> Type[GranuleQuery]:
     """Returns a query builder instance for data granules
 
-    Parameters:
-        cloud_hosted (Boolean): initializes the query builder for a particular DOI
-        if we have it.
     Returns:
-        class earthaccess.DataGranules: a query builder instance for data granules.
+        a query builder instance for data granules.
     """
     if earthaccess.__auth__.authenticated:
         query_builder = DataGranules(earthaccess.__auth__)
@@ -278,7 +268,7 @@ def get_fsspec_https_session() -> AbstractFileSystem:
     """Returns a fsspec session that can be used to access datafiles across many different DAACs
 
     Returns:
-        class AbstractFileSystem: an fsspec instance able to access data across DAACs
+        an fsspec instance able to access data across DAACs
 
     Examples:
         ```python
@@ -301,7 +291,7 @@ def get_requests_https_session() -> requests.Session:
     require authentication with NASA EDL.
 
     Returns:
-        class requests.Session: an authenticated requests Session instance.
+        an authenticated requests Session instance.
 
     Examples:
         ```python
@@ -326,12 +316,12 @@ def get_s3fs_session(
     """Returns a fsspec s3fs file session for direct access when we are in us-west-2
 
     Parameters:
-        daac (String): Any DAAC short name e.g. NSIDC, GES_DISC
-        provider (String): Each DAAC can have a cloud provider, if the DAAC is specified, there is no need to use provider
-        results (list[class earthaccess.results.DataGranule]): A list of results from search_data(), earthaccess will use the metadata form CMR to obtain the S3 Endpoint
+        daac: Any DAAC short name e.g. NSIDC, GES_DISC
+        provider: Each DAAC can have a cloud provider, if the DAAC is specified, there is no need to use provider
+        results: A list of results from search_data(), earthaccess will use the metadata form CMR to obtain the S3 Endpoint
 
     Returns:
-        class s3fs.S3FileSystem: an authenticated s3fs session valid for 1 hour
+        an authenticated s3fs session valid for 1 hour
     """
     daac = _normalize_location(daac)
     provider = _normalize_location(provider)
@@ -348,8 +338,7 @@ def get_edl_token() -> str:
     """Returns the current token used for EDL
 
     Returns:
-        str: EDL token
-
+        EDL token
     """
     token = earthaccess.__auth__.token
     return token