Rearranging the documentation again

GeoRegionsEcosystem · Sep 7, 2024 · 437b0bb · 437b0bb
1 parent c4a3bc5
commit 437b0bb
Show file tree

Hide file tree

Showing 7 changed files with 65 additions and 12 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -36,26 +36,26 @@ makedocs(;
         "Home" => "index.md",
         "What is a GeoRegion?"  => "georegions.md",
         "Basic Functionality" => [
-            "Retrieving GeoRegions" => "basics/read.md",
-            "Predefined GeoRegions" => "basics/predefined.md",
-            "GeoRegion Properties"  => "basics/shape.md",
+            "Retrieving GeoRegions"  => "basics/read.md",
+            "Predefined GeoRegions"  => "basics/predefined.md",
+            "GeoRegion Properties"   => "basics/shape.md",
+            "Table of GeoRegions"    => "basics/tables.md",
+            "Listing All GeoRegions" => "basics/listall.md",
         ],
         "Customizing GeoRegions.jl" => [
-            "Setup GeoRegions.jl"    => "custom/setup.md",
             "Create, Save, Retrieve" => "custom/overview.md",
-            "Defining RectRegions"   => "custom/rectregion.md",
-            "Defining PolyRegions"   => "custom/polyregion.md",
-            # "Defining TiltRegions"   => "custom/tiltregion.md",
+            "Project Setup"          => "custom/setup.md",
+            "More on Creation" => [
+                "Creating RectRegions"   => "custom/create/rectregion.md",
+                "Creating PolyRegions"   => "custom/create/polyregion.md",
+                # "Creating TiltRegions"   => "custom/create/tiltregion.md",
+            ],
             "Custom GeoRegion Files" => "custom/files.md",
         ],
         # "Tutorials" => [
         #     "Is it in a GeoRegion?" => "using/isin.md",
         #     "Custom GeoRegions"     => "using/custom.md",
         # ],
-        "Tables of GeoRegions"   => [
-            "Lists of predefined GeoRegions" => "lists/default.md",
-            # "Customized Lists of GeoRegions"     => "lists/api.md",
-        ],
     ],
 )
 

diff --git a/docs/src/lists/default.md → docs/src/basics/listall.md b/docs/src/lists/default.md → docs/src/basics/listall.md
diff --git a/docs/src/basics/tables.md b/docs/src/basics/tables.md
@@ -0,0 +1,20 @@
+# Tabular Listings of GeoRegions
+
+A list of GeoRegions and their basic properties can be called using the function `tableGeoRegions()`, which lists all available GeoRegions, both predefined and [custom/user-defined](/custom/overview). You can also choose to list only predefined or user-customized GeoRegions by setting their respective keywords arguments to `true/false`.
+
+```julia
+tableGeoRegions()
+```
+
+!!! tip "Additional Functionality for `tableGeoRegions()`"
+    It is possible to use `tableGeoRegions()` to list user-defined `GeoRegion`s in specific paths/directories. By default, it will list user-defined `GeoRegion`s saved into the path `joinpath(DEPOT_PATH[1],"files","GeoRegions")`. For more on user-defined GeoRegions and saving them as part of a larger project, refer to how to [setup](/custom/setup) GeoRegions.jl for a project. Full API documentation for `tableGeoRegions()` is given [here](/custom/overview).
+
+## More specific lists of GeoRegions
+
+Besides listing all available GeoRegions, it is also possible to list a variety of different subtypes of GeoRegions with the `tableRectRegions()`, `tableTiltRegions()` and `tablePolyRegions()`.
+
+```@docs
+tableRectRegions
+tableTiltRegions
+tablePolyRegions
+```
diff --git a/docs/src/custom/polyregion.md → docs/src/custom/create/polyregion.md b/docs/src/custom/polyregion.md → docs/src/custom/create/polyregion.md
diff --git a/docs/src/custom/rectregion.md → docs/src/custom/create/rectregion.md b/docs/src/custom/rectregion.md → docs/src/custom/create/rectregion.md
diff --git a/docs/src/custom/files.md b/docs/src/custom/files.md
@@ -1,2 +1,10 @@
 # Reading in a file with a list of Custom `GeoRegion`
 
+
+## Listing GeoRegions inside Custom Files
+
+It is possible to list the GeoRegions in specified file. The template for these files can be retrieved using the function `setupGeoRegions()`
+
+```@docs
+tableGeoRegions(fname::AbstractString)
+```
diff --git a/docs/src/custom/overview.md b/docs/src/custom/overview.md
@@ -15,6 +15,11 @@ TiltRegion(ID, pID, name, ...)
 PolyRegion(ID, pID, name, ...)
 ```
 
+Please refer to the respective pages dedicated to each of the `GeoRegion` subtypes:
+* [RectRegion](/custom/create/rectregion)
+* [PolyRegion](/custom/create/polyregion)
+* [TiltRegion](/custom/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`.
 
@@ -36,7 +41,11 @@ You can also add a `GeoRegion` variable in the workspace that you have not yet s
 
 ```julia
 geo = PolyRegion(ID, pID, name, ...)
-add(geo, path = "<directory>")
+add(geo, path = ...)
+```
+
+```@docs
+add
 ```
 
 ## Calling saved GeoRegions
@@ -45,4 +54,20 @@ If a GeoRegion has been saved to a `path`, it and its properties can be called u
 
 ```julia
 geo = GeoRegion(ID, path = "<directory>")
+```
+
+```@docs
+GeoRegion(ID::AbstractString; path::AbstractString)
+```
+
+## Table of user-defined GeoRegions
+
+You can create a table of all the `GeoRegion`s that have been saved to `path` using `tableGeoRegions()` as follows.
+
+```julia
+tableGeoRegions(;path = ...)
+```
+
+```@docs
+tableGeoRegions(; path::AbstractString, predefined::Bool, custom::Bool)
 ```