Updating documentation

docs/make.jl

@@ -37,7 +37,12 @@ makedocs(;
         "GeoRegions" => [
             "What is a GeoRegion?"  => "georegions/intro.md",
             "Predefined GeoRegions" => "georegions/predefined.md",
-            "Creating GeoRegions"   => "georegions/create.md",
+            "Using GeoRegions.jl"   => [
+                "An Overview"        => "georegions/using/overview.md",
+                "RectRegion Example" => "georegions/using/rectregion.md",
+                "PolyRegion Example" => "georegions/using/polyregion.md",
+                "TiltRegion Example" => "georegions/using/tiltregion.md",
+            ]
             # "Retrieving GeoRegions" => "georegions/read.md",
         ],
         # "Tutorials" => [

docs/src/georegions/intro.md

@@ -6,7 +6,7 @@ In essence, a `GeoRegion` is:
 * a subregion of a **parent** `GeoRegion` (identified by `pID`, which must also be a valid `ID`)
 
 !!! tip "Default GeoRegions"
-    When using `GeoRegions.jl`, the default `GeoRegion` should generally be the global domain, specified by `GLB` and given by the `[N,S,E,W]` coordinates `[90,-90,360,0]`.  The Global GeoRegion `GLB` is considered to be a subset of itself.
+    When using GeoRegions.jl, the default `GeoRegion` should generally be the global domain, specified by `GLB` and given by the `[N,S,E,W]` coordinates `[90,-90,360,0]`.  The Global GeoRegion `GLB` is considered to be a subset of itself.
 
 ```@docs
 GeoRegion

docs/src/georegions/using/overview.md

@@ -0,0 +1,48 @@
+# Using GeoRegions.jl to specify custom GeoRegions
+
+Recall that there are three different types of `GeoRegion`s: (a) `RectRegion`s, (b) `TiltRegion`s and (c) `PolyRegion`s.
+
+## Creating new GeoRegions
+
+We use the functions `RectRegion()`, `TiltRegion()` and `PolyRegion` to create new `GeoRegion`s of their respective types. Regardless of `GeoRegion` type, the **first three inputs are always the same**, in respective order:
+1. The ID (`ID`)
+2. parent `GeoRegion` ID, (`pID`)
+3. Name of the GeoRegion (`name`)
+
+```julia
+RectRegion(ID, pID, name, ...)
+TiltRegion(ID, pID, name, ...)
+PolyRegion(ID, pID, name, ...)
+```
+
+!!! warning "Constraints on `ID` and `pID` when `save = true`"
+    When `save = true`, the GeoRegion `pID` must already have been previously defined, and the region defined by the GeoRegion `ID` must be entirely within the region defined by the GeoRegion `pID`.
+
+## Saving new GeoRegions
+
+As of `≥v7` and above, new GeoRegions are no longer automatically saved. If you wish to automatically save a new GeoRegions **as it is created**, specify the keyword argument `save = true`. To specify the directory to which the GeoRegion information is saved to, use the `path` keyword.
+
+* `RectRegion(ID, pID, name, ..., save = true, path = ...)` writes to `$path/rectlist.txt`
+* `TiltRegion(ID, pID, name, ..., save = true, path = ...)` writes to `$path/tiltlist.txt`
+* `PolyRegion(ID, pID, name, ..., save = true, path = ...)` writes to `$path/polylist.txt`
+
+!!! tip "Default `path` Directory"
+    By default, `path = joinpath(DEPOT_PATH[1],"files","GeoRegions")`. If `path` is not specified, the information will be saved in the respective custom lists in this directory.
+
+!!! warning "Modification of Custom Lists"
+    While it is possible to do manually modify the lists, it is not recommended to do so, especially for `polylist.txt`, which is pretty complicated. Instead, you should let GeoRegions.jl do most of the heavy lifting.
+
+You can also add a `GeoRegion` variable in the workspace that you have not yet saved into the custom lists
+
+```julia
+geo = PolyRegion(ID, pID, name, ...)
+add(geo, path = "<directory>")
+```
+
+## Calling saved GeoRegions
+
+If a GeoRegion has been saved to a `path`, it and its properties can be called using its `ID` using the function `GeoRegion()`. There is no need to specify the GeoRegion subtype, as `GeoRegion`s with the same `ID` **cannot** be saved to the same `path`, even if they are of different subtypes.
+
+```julia
+geo = GeoRegion(ID, path = "<directory>")
+```

docs/src/georegions/using/polyregion.md

@@ -0,0 +1,24 @@
+# Defining New `PolyRegion`s
+
+Out of all three `GeoRegion` types currently available, the `PolyRegion` grants the most flexibility in terms of specification of the domain shape. With it, you can specify any closed polygon on a rectilinear grid using two vectors, for `lon` and `lat` respectively.
+
+!!! tip "Longitude and Latitude Vectors must be the same length"
+    As state in the header, the `lon` and `lat` vectors must be of the same length.
+
+```julia
+PolyRegion(ID, pID, name, lon, lat)
+```
+
+For example, we construct the sample `RectRegion` `TPR`, with longitude (`lon`) and latitude (`lat`) vectors of `[30,40,50,40,30]` and `[20,30,20,10,20]`
+
+```@repl
+using GeoRegions
+PolyRegion("TPR","GLB","Test Polygonal Region",[30,40,50,40,30],[20,30,20,10,20])
+```
+
+```@docs
+PolyRegion(
+    ::AbstractString, ::AbstractString, ::AbstractString,
+    ::Vector{<:Real}, ::Vector{<:Real}
+)
+```

docs/src/georegions/using/rectregion.md

@@ -0,0 +1,32 @@
+# Defining New `RectRegion`s
+
+Out of all three `GeoRegion` types currently available, the `RectRegion` is most straightforward to define. All you need to do is specify the `[N, S, E, W]` boundaries, in that order.
+
+```julia
+RectRegion(ID, pID, name, [N, S, E, W])
+```
+## Example
+
+As an example construct the sample `RectRegion`, with `ID` `TRR`, `pID` `GLB` and with the `name` as `Test Rectangle Region`
+
+```@repl
+using GeoRegions
+RectRegion("TRR","GLB","Test Rectangle Region",[30,20,50,10])
+```
+
+!!! tip "Constraints on N, S, E, W bounds"
+    The following are the constraints on the North, South, East and West bounds:
+    1. N > S
+    2. E > W
+    3. -90 ≤ N,S ≤ 90
+    4. -180 ≤ E,W ≤ 360
+    5. (E - W) < 360
+
+## API
+
+```@docs
+RectRegion(
+    ::AbstractString, ::AbstractString, ::AbstractString,
+    ::Vector{<:Real}
+)
+```