make docs good

Author: asinghvi17

docs/Project.toml

@@ -1,3 +1,8 @@
 [deps]
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+Chairmarks = "0ca39b1e-fe0b-4e98-acfc-b1656634c4de"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+GeoInterface = "cf35fbd7-0cd7-5166-be24-54bfbe79505f"
+GeoInterfaceMakie = "0edc0954-3250-4c18-859d-ec71c1660c08"
+NaturalEarth = "436b0209-26ab-4e65-94a9-6526d86fea76"
 TGGeometry = "d7e755d2-3c95-4bcf-9b3c-79ab1a78647b"

docs/src/index.md

@@ -4,11 +4,127 @@ CurrentModule = TGGeometry
 
 # TGGeometry
 
-Documentation for [TGGeometry](https://github.com/JuliaGeo/TGGeometry.jl).
+TGGeometry.jl is a Julia wrapper around the [`tg`](https://github.com/tidwall/tg) C library for planar geometric predicates.  Specifically, it provides:
+
+- [`intersects(geom1, geom2)`](@ref intersects)
+- [`contains(geom1, geom2)`](@ref contains)
+- [`touches(geom1, geom2)`](@ref touches)
+- [`disjoint(geom1, geom2)`](@ref disjoint)
+- [`equals(geom1, geom2)`](@ref equals)
+- [`covers(geom1, geom2)`](@ref covers)
+- [`coveredby(geom1, geom2)`](@ref coveredby)
+- [`within(geom1, geom2)`](@ref within)
+
+from the [DE-9IM](https://en.wikipedia.org/wiki/DE-9IM) model.
+
+It is fully [GeoInterface.jl](https://github.com/JuliaGeo/GeoInterface.jl) compatible, and is able to accept any combination of GeoInterface-compatible geometries as input (from GeoDataFrames, GeoJSON, ArchGDAL, GeometryOps, and many more packages!).
 
 ```@index
 ```
 
-```@autodocs
-Modules = [TGGeometry]
+## Quick start
+
+### Installation
+
+Install via `]add TGGeometry` in the REPL, or `Pkg.add("TGGeometry")`.
+
+### Basic usage
+
+Since TGGeometry allows any GeoInterface-compatible geometry as input, let's start with some geometries from NaturalEarth.jl:
+```@example quickstart
+using NaturalEarth
+using TGGeometry
+all_countries = naturalearth("admin_0_countries", 10)
+germany = all_countries.geometry[findfirst(==("Germany"), all_countries.NAME)]
+belgium = all_countries.geometry[findfirst(==("Belgium"), all_countries.NAME)]
+using CairoMakie, GeoInterfaceMakie
+f, a, p = poly(germany; label = "Germany", axis = (; aspect = DataAspect(),)) # hide
+poly!(a, belgium; label = "Belgium") # hide
+leg = axislegend(a) # hide
+hidedecorations!(a) # hide
+f # hide
+```
+
+```@example quickstart
+TGGeometry.intersects(germany, belgium)
+```
+
+```@example quickstart
+TGGeometry.contains(germany, belgium)
 ```
+
+```@example quickstart
+TGGeometry.touches(germany, belgium)
+```
+
+```@example quickstart
+TGGeometry.disjoint(germany, belgium)
+```
+
+You can use any data loader, like GeoJSON, GeoDataFrames, ArchGDAL, etc.  You can also construct your own geometries via GeometryBasics, GeoInterface wrapper geometries, or accepted basic types like 2-tuple points.
+
+```@example quickstart
+berlin = (13.4050, 52.5200) # berlin (longitude, latitude)
+scatter!(a, [berlin], color = :red, label = "Berlin") # hide
+delete!(leg) # hide
+leg = axislegend(a) # hide
+f # hide`
+```
+
+```@example quickstart
+TGGeometry.contains(germany, berlin)
+```
+
+### "Preparing" using `TGGeom`
+
+TGGeometry is fast naturally, but you can make it even faster by "preparing" your geometries by converting them to `TGGeom`s.  This converts the geometries to opaque pointers to a `tg` geometry - still fully GeoInterface-compatible though, but they have the acceleration benefits and don't have to be continually converted every time you call a predicate.
+
+The way to convert is to call `GeoInterface.convert(TGGeometry, geom)`.  This will convert the geometry to a `TGGeom` and return the new `TGGeom` object.
+
+Let's see the difference in speed, between using a `TGGeom` and a GeoJSON polygon:
+
+```@example quickstart
+using Chairmarks, GeoInterface
+gj_bench = @be TGGeometry.contains($germany, $berlin)
+```
+
+```@example quickstart
+# Convert to TGGeom
+germany_tg = GeoInterface.convert(TGGeometry, germany)
+
+tg_bench = @be TGGeometry.contains($germany_tg, $berlin)
+```
+
+The prepared approach is about **340x** faster!
+
+## Predicates
+
+Predicates from the DE-9IM model are available (but not a full `relate` function that would return the full DE-9IM matrix).
+
+```@docs
+intersects
+contains
+touches
+disjoint
+equals
+covers
+coveredby
+within
+```
+
+## TGGeom
+
+The `TGGeom` type is a wrapper around the `tg_geom` object returned by the `tg` library.  It is fully [GeoInterface.jl](https://github.com/JuliaGeo/GeoInterface.jl) compatible, and is able to accept any combination of GeoInterface-compatible geometries as input (from GeoDataFrames, GeoJSON, ArchGDAL, GeometryOps, and many more packages!).
+
+```@docs
+TGGeom
+```
+
+## Installation
+
+It's as simple as `]add TGGeometry`.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+