Updating and rearranging documentation

docs/make.jl

@@ -18,31 +18,33 @@ makedocs(;
         repo = "https://github.com/GeoRegionsEcosystem/GeoRegions.jl",
     ),
     pages=[
-        "Home" => "index.md",
-        "What is a GeoRegion?"  => "georegions.md",
+        "Home"                      => "index.md",
+        "What is a GeoRegion?"      => "georegions.md",
         "Basic Functionality" => [
-            "Retrieving GeoRegions"  => [
+            "Retrieving GeoRegions" => [
                 "Overview (START HERE)"  => "basics/read/overview.md",
                 "Predefined GeoRegions"  => "basics/read/predefined.md",
                 "Tabulating GeoRegions"  => "basics/read/tables.md",
                 "Listing All GeoRegions" => "basics/read/listall.md",
-            ]
-            "GeoRegion Properties"   => [
+            ],
+            "Creating GeoRegions"   => "basics/create.md",
+            "GeoRegion Properties"  => [
                 "Shape of a GeoRegion"  => "basics/properties/shape.md",
                 "Is it in a GeoRegion?" => "basics/properties/isin.md",
             ]
         ],
-        "GeoRegions.jl Tutorials" => [
+        "GeoRegions.jl Tutorials"   => [
             "Setup (START HERE)"     => "tutorials/setup.md",
             "Create, Save, Retrieve" => "tutorials/overview.md",
-            "More on Creation" => [
-                "Creating RectRegions"   => "tutorials/create/rectregion.md",
-                "Creating PolyRegions"   => "tutorials/create/polyregion.md",
-                "Creating TiltRegions"   => "tutorials/create/tiltregion.md",
-            ],
             "Custom GeoRegion Files" => "tutorials/files.md",
         ],
-        "Ecosystem"  => "ecosystem.md",
+        "API"                       => [
+            "Creation" => "api/create.md",
+            # "Add"      => "api/add.md",
+            # "Read"     => "api/read.md",
+            # "Tables"   => "api/tables.md",
+        ],
+        "Ecosystem"                 => "ecosystem.md",
     ],
 )
 

docs/src/api/create.md

@@ -0,0 +1,22 @@
+# API for Creating GeoRegions
+
+```@docs
+RectRegion(
+    ::AbstractString, ::AbstractString, ::AbstractString,
+    ::Vector{<:Real}
+)
+```
+
+```@docs
+TiltRegion(
+    ::AbstractString, ::AbstractString, ::AbstractString,
+    ::Real, ::Real, ::Real, ::Real, ::Real
+)
+```
+
+```@docs
+PolyRegion(
+    ::AbstractString, ::AbstractString, ::AbstractString,
+    ::Vector{<:Real}, ::Vector{<:Real}
+)
+```

docs/src/basics/create.md

@@ -0,0 +1,72 @@
+# Creating 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, ...)
+```
+
+## 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.
+
+!!! 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
+
+```julia
+RectRegion(ID, pID, name, [N, S, E, W])
+```
+
+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])
+```
+
+## 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])
+```
+
+## Defining New `TiltRegion`s
+
+Text
+
+```julia
+TiltRegion(ID, pID, name, X, Y, ΔX, ΔY, θ)
+```
+
+As an example construct the sample `TiltRegion`, with `ID` `TTR`, `pID` `GLB` and with the `name` as `Test Rectangle Region`
+
+```@repl
+using GeoRegions
+RectRegion("TTR","GLB","Test Rectangle Region",10,5,50,20,30)
+```

docs/src/tutorials/overview.md

@@ -1,31 +1,6 @@
 # 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, ...)
-```
-
-Please refer to the respective pages dedicated to each of the `GeoRegion` subtypes:
-* [RectRegion](/tutorials/create/rectregion)
-* [PolyRegion](/tutorials/create/polyregion)
-* [TiltRegion](/tutorials/create/tiltregion)
-
-!!! 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.
+New GeoRegions can be no longer automatically saved if so specified. 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`
@@ -44,8 +19,8 @@ geo = PolyRegion(ID, pID, name, ...)
 add(geo, path = ...)
 ```
 
-```@docs
-add
+```@example using
+
 ```
 
 ## Calling saved GeoRegions
@@ -56,8 +31,8 @@ If a GeoRegion has been saved to a `path`, it and its properties can be called u
 geo = GeoRegion(ID, path = "<directory>")
 ```
 
-```@docs
-GeoRegion(ID::AbstractString; path::AbstractString)
+```@example using
+
 ```
 
 ## Table of user-defined GeoRegions
@@ -68,6 +43,6 @@ You can create a table of all the `GeoRegion`s that have been saved to `path` us
 tableGeoRegions(;path = ...)
 ```
 
-```@docs
-tableGeoRegions(; path::AbstractString, predefined::Bool, custom::Bool)
+```@example using
+
 ```