Some documentation updates

Author: natgeo-wong

docs/Project.toml

@@ -3,3 +3,6 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 LandSea = "cbf7bb22-a1a6-46cb-8b24-174e3bc5fc04"
+
+[compat]
+DocumenterVitepress = "0.2"

docs/make.jl

@@ -15,9 +15,8 @@ makedocs(;
     ),
     pages=[
         "Home"            => "index.md",
-        "Getting Started" => "landsea.md",
-        # "Basic Example"   => "example.md",
-        "API List"        => "api.md",
+        "Getting Started" => "basics.md",
+        "Dataset Types"   => "landsea.md",
     ],
 )
 

docs/src/api.md

@@ -0,0 +1,34 @@
+# How to use LandSea.jl
+
+As mentioned on the [home](index) page, LandSea.jl is a backend package that allows a user to import and handle land-sea masks and topographic data. Examples of such land-sea mask datasets include:
+* ERA5 reanalysis land-sea masks and topographic data (0.25º or T639 spectral)
+* NASA IMERG land-sea mask (0.1º)
+* ETOPO topographic datasets, with land-sea mask estimation
+
+## Retrieving a LandSea Dataset
+
+To retrieve Land-Sea dataset, we recommend extending the `getLandSea()` function exported by LandSea.jl as needed via the following method:
+
+```julia
+import LandSea: getLandSea
+
+function getLandSea(
+    ids :: <Dataset Type of Interest>,
+    geo :: GeoRegion
+)
+
+...
+
+end
+```
+
+See the docs below:
+```@docs
+getLandSea
+```
+
+## Examples
+
+The following packages serve as examples of how LandSea.jl can be used to download topographic and land-sea mask information:
+* ERA5Reanalysis.jl [(GitHub)](https://github.com/GeoRegionsEcosystem/ERA5Reanalysis.jl) [(documentation)](https://georegionsecosystem.github.io/ERA5Reanalysis.jl/stable/) [(source code)](https://github.com/GeoRegionsEcosystem/ERA5Reanalysis.jl/tree/main/src/landsea)
+* NASAPrecipitation.jl [(GitHub)](https://github.com/GeoRegionsEcosystem/NASAPrecipitation.jl) [(documentation)](https://georegionsecosystem.github.io/NASAPrecipitation.jl/stable/) [(source code)](https://github.com/GeoRegionsEcosystem/NASAPrecipitation.jl/tree/main/src/landsea)

docs/src/basics.md

@@ -5,8 +5,21 @@ A `LandSeaData` type contains information on:
 * The Land-Sea mask containing information on how where land and ocean are in the region of interest
 * The topography, where available, of the region of interest
 
-## The Types of `LandSeaData`s
+```@docs
+LandSeaData
+```
 
 The `LandSeaData` abstract type has two subtypes:
 1. `LandSeaFlat` type, which contains only information on the Land-Sea mask but has no information on topography
-2. `LandSeaTopo` type, which contains information on both the Land-Sea mask and the topography
+2. `LandSeaTopo` type, which contains information on both the Land-Sea mask and the topography
+
+## The `LandSeaFlat` Type
+
+```@docs
+LandSeaFlat
+```
+## The `LandSeaTopo` Type
+
+```@docs
+LandSeaTopo
+```

docs/src/landsea.md

@@ -19,10 +19,10 @@ export
 Abstract supertype for LandSea Datasets. All `LandSeaData` types contain the following fields:
 * `lon` - Vector containing the longitude points for the Land-Sea Dataset
 * `lat` - Vector containing the latitude points for the Land-Sea Dataset
-* `lsm` - Vector or Array containing data regarding the Land-Sea Mask. 1 is Land, 0 is Ocean, NaN is outside the bounds of the GeoRegion
+* `lsm` - Vector or Matrix containing data regarding the Land-Sea Mask. 1 is Land, 0 is Ocean, NaN is outside the bounds of the GeoRegion.
 
 !!! info
-    If `lsm` is a vector, then `lon`, `lat` and `lsm` all must have the same length
+    If `lsm` is a vector, then `lon`, `lat` and `lsm` all must have the same length. Otherwise if `lsm` is a matrix, then its first and second dimensions are longitude and latitude respectively, and it must have size `length(lon)` and `length(lat)`.
 """
 abstract type LandSeaData end
 
@@ -34,8 +34,17 @@ A LandSea Dataset that also contains information on the topographic height.
 A `LandSeaTopo` type will also contain the following field:
 * `z` - Vector or Array containing data regarding the Orographic Height in meters. NaN is outside the bounds of the GeoRegion
 
+A `LandSeaTopo` type can be created using the function:
+
+    LandSeaTopo(
+        lon :: Vector{FT1},
+        lat :: Vector{FT1},
+        lsm :: Union{Vector{FT2},Matrix{FT2}},
+        z   :: Union{Vector{FT2},Matrix{FT2}}
+    ) where {FT1 <: Real, FT2 <: Real} -> LandSeaTopo
+
 !!! info
-    If `z` or `lsm` are vectors, then `lon`, `lat`, `lsm` and `z` all must be vectors of the same length
+    `z` and `lsm` must both be either (1) vectors or (2) matrices of the same size. If `lsm` and `z` are vectors, then `lon`, `lat`, `lsm` and `z` all must have the same length. Otherwise if `lsm` and `z` are matrices, then their first and second dimensions are longitude and latitude respectively, and they are of size `length(lon)` and `length(lat)`.
 """
 struct LandSeaTopo{FT1<:Real,FT2<:Real} <: LandSeaData
 
@@ -94,6 +103,14 @@ end
     LandSeaFlat <: LandSeaData
 
 A LandSea Dataset that contains only information on the land-sea mask and no topography.
+
+A `LandSeaFlat` type can be created using the function:
+
+    LandSeaFlat(
+        lon :: Vector{FT1},
+        lat :: Vector{FT1},
+        lsm :: Union{Vector{FT2},Matrix{FT2}}
+    ) where {FT1 <: Real, FT2 <: Real} -> LandSeaTopo
 """
 struct LandSeaFlat{FT1<:Real,FT2<:Real} <: LandSeaData
 
@@ -129,6 +146,16 @@ modulelog() = "$(now()) - LandSea.jl"
     getLandSea
 
 An extensible function type to retrieve LandSea Datasets. You can use this function name in your packages if you want to retrieve a specific LandSea dataset.
+
+    getLandSea(
+        ids :: <Dataset Type of Interest>,
+        geo :: GeoRegion
+    ) -> LandSeaData
+
+Arguments
+=========
+- `ids`  : A `struct` type for the dataset of interest (e.g., a [`NASAPrecipitationDataset`](https://georegionsecosystem.github.io/NASAPrecipitation.jl/stable/datasets/intro))
+- `geo`  : A `GeoRegion` structure type
 """
 function getLandSea end