Merge pull request #200 from Maxxen/dev

Small Bugfixes, Initial docs scaffolding
duckdb · Nov 27, 2023 · 1da1f6f · 1da1f6f
2 parents d3f5332 + b56e9e2
commit 1da1f6f
Show file tree

Hide file tree

Showing 102 changed files with 6,382 additions and 2 deletions.
diff --git a/docs/docs.md b/docs/docs.md
diff --git a/docs/src/README.md b/docs/src/README.md
@@ -0,0 +1,80 @@
+# DuckDB Spatial Docs
+
+This directory contains the source code for the DuckDB Spatial documentation.
+
+## Building the docs
+
+The full `docs.md` file is generated from the source files in this directory (`/docs/src/`) using a simple `generate.py` python3 script that lightly formats and concatenates a bunch of separate markdown files. To build the docs, simply run:
+
+```bash
+python3 generate.py
+```
+
+and the `docs.md` file will be generated in the parent directory (`/docs/docs.md`)
+
+## Writing docs
+The docs are written in Markdown, with some additional metadata stored in a json "frontmatter". The metadata is used to generate the `docs.md` file. Each function has its own file, with the filename corresponding to the function name. For example, the `ST_AsGeoJSON` function is documented in the `/functions/scalar/st_asgeojson.md` file. These file are the source of truth for the documentation, and the `docs.md` file is generated from these files. 
+
+**Do not edit the `docs.md` file directly**.
+
+### Frontmatter
+The frontmatter is a json object that contains metadata about the documentation item. The frontmatter is enclosed in a pair of `---` lines, and is the first thing in the file. For example, the frontmatter for the `ST_AsGeoJSON` function is:
+
+```json
+---
+{
+    "id": "st_asgeojson",
+    "title": "ST_AsGeoJSON",
+    "type": "scalar_function",
+    "signatures": [
+        {
+            "returns": "VARCHAR",
+            "parameters": [
+                {
+                    "name": "geom",
+                    "type": "GEOMETRY"
+                }
+            ]
+        }
+    ],
+    "aliases": [],
+    "summary": "Returns the geometry as a GeoJSON fragment",
+    "tags": [
+        "conversion"
+    ]
+}
+---
+```
+
+The frontmatter always contains the following fields:
+
+| Field | Description |
+| --- | --- |
+| `type` | The documentation item type. e.g. `scalar_function`, `aggregate_function`, `table_function` |
+| `id` | The documentation item id (unique, used internally by the doc generator) |
+
+#### Functions 
+Scalar and aggregate functions have the following additional fields:
+
+| Field | Description |
+| --- | --- |
+| `title` | The function title (capitalized, human friendly name) |
+| `signatures` | An array of function signatures. See signatures below |
+| `aliases` | An array of function aliases. |
+| `summary` | A short summary of the function |
+| `tags` | An array of tags for the function. e.g. `conversion`, `geometry`, `measurement` |
+
+Since functions can be overloaded, the `signatures` field is an array of function signatures. Each signature has the following fields:
+
+| Field | Description |
+| --- | --- |
+| `returns` | The return type of the function, in SQL |
+| `parameters` | An array of function parameters. See parameters below |
+
+Each function parameter has the following fields:
+
+| Field | Description |
+| --- | --- |
+| `name` | The parameter name |
+| `type` | The parameter type, in SQL |
+
diff --git a/docs/src/aggregate_functions.json b/docs/src/aggregate_functions.json
@@ -0,0 +1,3 @@
+{"type":"aggregate_function","id":"st_intersection_agg","title":"ST_Intersection_Agg","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]}
+{"type":"aggregate_function","id":"st_envelope_agg","title":"ST_Envelope_Agg","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]}
+{"type":"aggregate_function","id":"st_union_agg","title":"ST_Union_Agg","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]}
diff --git a/docs/src/functions/aggregate/st_envelope_agg.md b/docs/src/functions/aggregate/st_envelope_agg.md
@@ -0,0 +1,31 @@
+---
+{
+    "type": "aggregate_function",
+    "title": "ST_Envelope_Agg",
+    "id": "st_envelope_agg",
+    "signatures": [
+        {
+            "returns": "GEOMETRY",
+            "parameters": [
+                {
+                    "name": "geom",
+                    "type": "GEOMETRY"
+                }
+            ]
+        }
+    ],
+    "summary": "Computes a minimal-bounding-box polygon 'enveloping' the set of input geometries",
+    "tags": [
+        "construction"
+    ]
+}
+---
+
+### Description
+
+TODO
+
+### Examples
+
+TODO
+
diff --git a/docs/src/functions/aggregate/st_intersection_agg.md b/docs/src/functions/aggregate/st_intersection_agg.md
@@ -0,0 +1,31 @@
+---
+{
+    "type": "aggregate_function",
+    "title": "ST_Intersection_Agg",
+    "id": "st_intersection_agg",
+    "signatures": [
+        {
+            "returns": "GEOMETRY",
+            "parameters": [
+                {
+                    "name": "geom",
+                    "type": "GEOMETRY"
+                }
+            ]
+        }
+    ],
+    "summary": "Computes the intersection of a set of geometries",
+    "tags": [
+        "construction"
+    ]
+}
+---
+
+### Description
+
+TODO
+
+### Examples
+
+TODO
+
diff --git a/docs/src/functions/aggregate/st_union_agg.md b/docs/src/functions/aggregate/st_union_agg.md
@@ -0,0 +1,31 @@
+---
+{
+    "type": "aggregate_function",
+    "title": "ST_Union_Agg",
+    "id": "st_union_agg",
+    "signatures": [
+        {
+            "returns": "GEOMETRY",
+            "parameters": [
+                {
+                    "name": "geom",
+                    "type": "GEOMETRY"
+                }
+            ]
+        }
+    ],
+    "summary": "Computes the union of a set of input geometries",
+    "tags": [
+        "construction"
+    ]
+}
+---
+
+### Description
+
+TODO
+
+### Examples
+
+TODO
+
diff --git a/docs/src/functions/scalar/st_area.md b/docs/src/functions/scalar/st_area.md
@@ -0,0 +1,73 @@
+---
+{
+    "id": "st_area",
+    "title": "ST_Area",
+    "type": "scalar_function",
+    "signatures": [
+        {
+            "returns": "DOUBLE",
+            "parameters": [
+                {
+                    "name": "geom",
+                    "type": "GEOMETRY"
+                }
+            ]
+        },
+        {
+            "returns": "DOUBLE",
+            "parameters": [
+                {
+                    "name": "point_2D",
+                    "type": "POINT_2D"
+                }
+            ]
+        },
+        {
+            "returns": "DOUBLE",
+            "parameters": [
+                {
+                    "name": "linestring_2d",
+                    "type": "LINESTRING_2D"
+                }
+            ]
+        },
+        {
+            "returns": "DOUBLE",
+            "parameters": [
+                {
+                    "name": "polygon_2d",
+                    "type": "POLYGON_2D"
+                }
+            ]
+        },
+        {
+            "returns": "DOUBLE",
+            "parameters": [
+                {
+                    "name": "box",
+                    "type": "BOX_2D"
+                }
+            ]
+        }
+    ],
+    "aliases": [],
+    "summary": "Returns the area of a geometry.",
+    "see_also": [ "st_area_spheroid", "st_perimeter" ],
+    "tags": [ "property" ]
+}
+---
+
+### Description
+
+Compute the area of a geometry.
+
+Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries.
+
+The `POINT_2D` and `LINESTRING_2D` variants of this function always return `0.0` but are included for completeness.
+
+### Examples
+
+```sql
+select ST_Area('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry);
+-- 1.0
+```
diff --git a/docs/src/functions/scalar/st_area_spheroid.md b/docs/src/functions/scalar/st_area_spheroid.md
@@ -0,0 +1,44 @@
+---
+{
+    "type": "scalar_function",
+    "title": "ST_Area_Spheroid",
+    "id": "st_area_spheroid",
+    "signatures": [
+        {
+            "returns": "DOUBLE",
+            "parameters": [
+                {
+                    "name": "polygon",
+                    "type": "POLYGON_2D"
+                }
+            ]
+        },
+        {
+            "returns": "DOUBLE",
+            "parameters": [
+                {
+                    "name": "geometry",
+                    "type": "GEOMETRY"
+                }
+            ]
+        }
+    ],
+    "summary": "Returns the area of a geometry in meters, using an ellipsoidal model of the earth",
+    "tags": [
+        "property",
+        "spheroid"
+    ]
+}
+---
+
+### Description
+
+The input geometry is assumed to be in the [EPSG:4326](https://en.wikipedia.org/wiki/World_Geodetic_System) coordinate system (WGS84), with [latitude, longitude] axis order and the area is returned in square meters. This function uses the [GeographicLib](https://geographiclib.sourceforge.io/) library, calculating the area using an ellipsoidal model of the earth. This is a highly accurate method for calculating the area of a polygon taking the curvature of the earth into account, but is also the slowest.
+
+Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries.
+
+
+### Examples
+
+TODO
+
diff --git a/docs/src/functions/scalar/st_asgeojson.md b/docs/src/functions/scalar/st_asgeojson.md
@@ -0,0 +1,38 @@
+---
+{
+    "id": "st_asgeojson",
+    "title": "ST_AsGeoJSON",
+    "type": "scalar_function",
+    "signatures": [
+        {
+            "returns": "VARCHAR",
+            "parameters": [
+                {
+                    "name": "geom",
+                    "type": "GEOMETRY"
+                }
+            ]
+        }
+    ],
+    "aliases": [],
+    "summary": "Returns the geometry as a GeoJSON fragment",
+    "tags": [
+        "conversion"
+    ]
+}
+---
+
+### Description
+
+Returns the geometry as a GeoJSON fragment. 
+
+This does not return a complete GeoJSON document, only the geometry fragment. To construct a complete GeoJSON document or feature, look into using the DuckDB JSON extension in conjunction with this function.
+
+### Examples
+
+```sql
+select ST_AsGeoJSON('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry);
+----
+{"type":"Polygon","coordinates":[[[0.0,0.0],[0.0,1.0],[1.0,1.0],[1.0,0.0],[0.0,0.0]]]}
+
+```
diff --git a/docs/src/functions/scalar/st_ashexwkb.md b/docs/src/functions/scalar/st_ashexwkb.md
@@ -0,0 +1,37 @@
+---
+{
+    "id": "st_ashexwkb",
+    "title": "ST_AsHEXWKB",
+    "type": "scalar_function",
+    "signatures": [
+        {
+            "returns": "VARCHAR",
+            "parameters": [
+                {
+                    "name": "geom",
+                    "type": "GEOMETRY"
+                }
+            ]
+        }
+    ],
+    "aliases": [],
+    "summary": "Returns the geometry as a HEXWKB string",
+    "description": "Actually returns HEXEWKB",
+    "tags": [
+        "conversion"
+    ],
+    "see_also": [
+        "st_aswkb"
+    ]
+}
+---
+
+### Description
+
+Returns the geometry as a HEXWKB string
+
+### Examples
+
+```sql
+select st_ashexwkb('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry);
+```