docs tweaks

generate_function_reference.py

@@ -41,7 +41,7 @@ def write_table_of_contents(f, functions):
     for function in functions:
         # Summary is the first line of the description
         summary = function['description'].split('\n')[0]
-        f.write(f"| [{function['name']}](#{to_kebab_case(function['name'])}) | {summary} |\n")
+        f.write(f"| [`{function['name']}`](#{to_kebab_case(function['name'])}) | {summary} |\n")
 
 
 def to_kebab_case(name):
@@ -76,11 +76,11 @@ def main():
             f.write(f"## {func_set[0]}\n\n")
             set_name = func_set[0]
             for function in func_set[1]:
-                f.write(f"### {function['name']}\n\n")
-                summary = function['description'].split('\n')[0]
-                f.write(f"_{summary}_\n\n")
-
-                f.write("#### Signature\n\n")
+                f.write(f"### {function['name']}\n\n\n")
+                #summary = function['description'].split('\n')[0]
+                #f.write(f"_{summary}_\n\n")
+                
+                f.write("#### Signature\n\n") if len(function['signatures']) == 1 else f.write("#### Signatures\n\n")
                 f.write("```sql\n")
                 for signature in function['signatures']:
                     param_list = ", ".join([f"{param['name']} {param['type']}" for param in signature['params']])
@@ -101,14 +101,15 @@ def main():
                     f.write("\n```\n\n")
                 else:
                     print(f"No example for {function['name']}")
-                f.write("\n\n")
+                #f.write("\n\n")
+                f.write("----\n\n")
 
         # Write table functions
         f.write("## Table Functions\n\n")
         for function in table_functions:
             f.write(f"### {function['name']}\n\n")
-            summary = function['description'].split('\n')[0]
-            f.write(f"_{summary}_\n\n")
+            #summary = function['description'].split('\n')[0]
+            #f.write(f"_{summary}_\n\n")
 
             f.write("#### Signature\n\n")
             f.write("```sql\n")
@@ -131,7 +132,7 @@ def main():
                 f.write("\n```\n\n")
             else:
                 print(f"No example for {function['name']}")
-            f.write("\n\n")
+            f.write("----\n\n")
 
 if __name__ == "__main__":
     main()

spatial/src/spatial/core/functions/scalar/st_area.cpp

@@ -179,17 +179,17 @@ static void GeometryAreaFunction(DataChunk &args, ExpressionState &state, Vector
 //------------------------------------------------------------------------------
 
 static constexpr const char *DOC_DESCRIPTION = R"(
-    Returns the area of a geometry.
-
     Compute the area of a geometry.
 
     Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries.
+	The area is in the same units as the spatial reference system of the geometry.
 
-    The `POINT_2D` and `LINESTRING_2D` variants of this function always return `0.0` but are included for completeness.
+    The `POINT_2D` and `LINESTRING_2D` overloads of this function always return `0.0` but are included for completeness.
 )";
 
 static constexpr const char *DOC_EXAMPLE = R"(
     select ST_Area('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry);
+	-- 1.0
 )";
 
 static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "property"}};

spatial/src/spatial/core/functions/scalar/st_asgeojson.cpp

@@ -561,12 +561,24 @@ static constexpr const char *AS_DOC_DESCRIPTION = R"(
     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.
+	This function supports geometries with Z values, but not M values.
 )";
 
 static constexpr const char *AS_DOC_EXAMPLE = R"(
 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]]]}
+
+-- Convert a geometry into a full GeoJSON feature (requires the JSON extension to be loaded)
+SELECT CAST({
+	type: 'Feature', 
+	geometry: ST_AsGeoJSON(ST_Point(1,2)), 
+	properties: { 
+		name: 'my_point' 
+	} 
+} AS JSON);
+----
+{"type":"Feature","geometry":{"type":"Point","coordinates":[1.0,2.0]},"properties":{"name":"my_point"}}
 )";
 
 // FromGeoJSON
@@ -575,7 +587,9 @@ static constexpr const char *FROM_DOC_DESCRIPTION = R"(
 )";
 
 static constexpr const char *FROM_DOC_EXAMPLE = R"(
-
+SELECT ST_GeomFromGeoJSON('{"type":"Point","coordinates":[1.0,2.0]}');
+----
+POINT (1 2)
 )";
 
 //------------------------------------------------------------------------------

spatial/src/spatial/core/functions/scalar/st_ashexwkb.cpp

@@ -53,6 +53,8 @@ static constexpr const char *DOC_DESCRIPTION = R"(
 
 static constexpr const char *DOC_EXAMPLE = R"(
 SELECT ST_AsHexWKB('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry);
+----
+01030000000100000005000000000000000000000000000...
 )";
 
 static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "conversion"}};

spatial/src/spatial/core/functions/scalar/st_assvg.cpp

@@ -159,9 +159,9 @@ static constexpr const char *DOC_DESCRIPTION = R"(
 )";
 
 static constexpr const char *DOC_EXAMPLE = R"(
-    select ST_AsSVG('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry, false, 15);
-	----
-	M 0 0 L 0 -1 1 -1 1 0 Z
+SELECT ST_AsSVG('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::GEOMETRY, false, 15);
+----
+M 0 0 L 0 -1 1 -1 1 0 Z
 )";
 
 static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "conversion"}};

spatial/src/spatial/core/functions/scalar/st_astext.cpp

@@ -74,7 +74,9 @@ static constexpr const char *DOC_DESCRIPTION = R"(
 )";
 
 static constexpr const char *DOC_EXAMPLE = R"(
-SELECT ST_AsText('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry);
+SELECT ST_AsText(ST_MakeEnvelope(0,0,1,1));
+----
+POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))
 )";
 
 static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "conversion"}};

spatial/src/spatial/core/functions/scalar/st_aswkb.cpp

@@ -31,7 +31,9 @@ static constexpr const char *DOC_DESCRIPTION = R"(
 )";
 
 static constexpr const char *DOC_EXAMPLE = R"(
-SELECT ST_AsWKB('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry);
+SELECT ST_AsWKB('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::GEOMETRY)::BLOB;
+----
+\x01\x03\x00\x00\x00\x01\x00\x00\x00\x05...
 )";
 
 static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "conversion"}};

spatial/src/spatial/core/functions/scalar/st_collect.cpp

@@ -82,7 +82,6 @@ static void CollectFunction(DataChunk &args, ExpressionState &state, Vector &res
 //------------------------------------------------------------------------------
 
 static constexpr const char *DOC_DESCRIPTION = R"(
-Collects geometries into a collection geometry
 
 Collects a list of geometries into a collection geometry.
 - If all geometries are `POINT`'s, a `MULTIPOINT` is returned.

spatial/src/spatial/core/functions/scalar/st_dump.cpp

@@ -117,7 +117,7 @@ static void DumpFunction(DataChunk &args, ExpressionState &state, Vector &result
 // Documentation
 //------------------------------------------------------------------------------
 static constexpr const char *DOC_DESCRIPTION = R"(
-Dumps a geometry into a set of sub-geometries and their "path" in the original geometry.
+Dumps a geometry into a list of sub-geometries and their "path" in the original geometry.
 )";
 
 static constexpr const char *DOC_EXAMPLE = R"(

spatial/src/spatial/core/functions/scalar/st_endpoint.cpp

@@ -87,11 +87,11 @@ static void GeometryEndPointFunction(DataChunk &args, ExpressionState &state, Ve
 // Documentation
 //------------------------------------------------------------------------------
 static constexpr const char *DOC_DESCRIPTION = R"(
-Returns the end point of a line.
+Returns the last point of a line.
 )";
 
 static constexpr const char *DOC_EXAMPLE = R"(
-select st_endpoint('LINESTRING(0 0, 1 1)'::geometry);
+select ST_EndPoint('LINESTRING(0 0, 1 1)'::geometry);
 -- POINT(1 1)
 )";
 

spatial/src/spatial/core/functions/scalar/st_hilbert.cpp

@@ -226,10 +226,10 @@ static void HilbertEncodeBoxFunction(DataChunk &args, ExpressionState &state, Ve
 //------------------------------------------------------------------------------
 static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "property"}};
 static constexpr const char *DOC_DESCRIPTION = R"(
-    Encodes the X and Y values as the hilbert curve index for a curve covering the given bounding box.
-
-	Only POINT geometries are supported for the GEOMETRY variant.
-	For the BOX_2D and BOX_2DF variants, the center of the box is used as the point to encode.
+Encodes the X and Y values as the hilbert curve index for a curve covering the given bounding box.
+If a geometry is provided, the center of the approximate bounding box is used as the point to encode.
+If no bounding box is provided, the hilbert curve index is mapped to the full range of a single-presicion float.
+For the BOX_2D and BOX_2DF variants, the center of the box is used as the point to encode.
 )";
 static constexpr const char *DOC_EXAMPLE = R"(
 

spatial/src/spatial/core/functions/scalar/st_ngeometries.cpp

@@ -41,8 +41,8 @@ static void GeometryNGeometriesFunction(DataChunk &args, ExpressionState &state,
 // Documentation
 //------------------------------------------------------------------------------
 static constexpr const char *DOC_DESCRIPTION = R"(
-    Returns the number of component geometries in a collection geometry
-    If the input geometry is not a collection, returns 1 if the geometry is not empty, otherwise 0
+    Returns the number of component geometries in a collection geometry.
+    If the input geometry is not a collection, this function returns 0 or 1 depending on if the geometry is empty or not.
 )";
 
 static constexpr const char *DOC_EXAMPLE = R"(

spatial/src/spatial/core/functions/scalar/st_quadkey.cpp

@@ -90,7 +90,6 @@ static void GeometryQuadKeyFunction(DataChunk &args, ExpressionState &state, Vec
 // Documentation
 //------------------------------------------------------------------------------
 static constexpr const char *DOC_DESCRIPTION = R"(
-Computes a quadkey from a given lon/lat point.
 
 Compute the [quadkey](https://learn.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system) for a given lon/lat point at a given level.
 Note that the the parameter order is __longitude__, __latitude__.
@@ -99,7 +98,7 @@ Note that the the parameter order is __longitude__, __latitude__.
 
 The input coordinates will be clamped to the lon/lat bounds of the earth (longitude between -180 and 180, latitude between -85.05112878 and 85.05112878).
 
-Throws for any geometry that is not a `POINT`
+The geometry overload throws an error if the input geometry is not a `POINT`
 )";
 
 static constexpr const char *DOC_EXAMPLE = R"(

spatial/src/spatial/core/functions/scalar/st_startpoint.cpp

@@ -87,7 +87,10 @@ static constexpr const char *DOC_DESCRIPTION = R"(
 Returns the first point of a line geometry
 )";
 
-static constexpr const char *DOC_EXAMPLE = R"()";
+static constexpr const char *DOC_EXAMPLE = R"(
+select ST_StartPoint('LINESTRING(0 0, 1 1)'::geometry);
+-- POINT(0 0)
+)";
 
 static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "construction"}};
 //------------------------------------------------------------------------------

spatial/src/spatial/core/io/osm/st_read_osm.cpp

@@ -864,7 +864,7 @@ static unique_ptr<TableRef> ReadOsmPBFReplacementScan(ClientContext &context, Re
 static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}};
 
 static constexpr const char *DOC_DESCRIPTION = R"(
-    The ST_ReadOsm() table function enables reading compressed OpenStreetMap data directly from a `.osm.pbf file.`
+    The `ST_ReadOsm()` table function enables reading compressed OpenStreetMap data directly from a `.osm.pbf file.`
 
     This function uses multithreading and zero-copy protobuf parsing which makes it a lot faster than using the `ST_Read()` OSM driver, however it only outputs the raw OSM data (Nodes, Ways, Relations), without constructing any geometries. For simple node entities (like PoI's) you can trivially construct POINT geometries, but it is also possible to construct LINESTRING and POLYGON geometries by manually joining refs and nodes together in SQL, although with available memory usually being a limiting factor.
     The `ST_ReadOSM()` function also provides a "replacement scan" to enable reading from a file directly as if it were a table. This is just syntax sugar for calling `ST_ReadOSM()` though. Example:

spatial/src/spatial/gdal/functions/st_read.cpp

@@ -621,7 +621,7 @@ static constexpr const char *DOC_DESCRIPTION = R"(
 
     The `ST_Read` table function is based on the [GDAL](https://gdal.org/index.html) translator library and enables reading spatial data from a variety of geospatial vector file formats as if they were DuckDB tables.
 
-    > See [ST_Drivers](##st_drivers) for a list of supported file formats and drivers.
+    > See [ST_Drivers](#st_drivers) for a list of supported file formats and drivers.
 
     Except for the `path` parameter, all parameters are optional.
 

spatial/src/spatial/geographiclib/functions/st_distance_within_spheroid.cpp

@@ -40,6 +40,8 @@ static void GeodesicPoint2DFunction(DataChunk &args, ExpressionState &state, Vec
 
 static constexpr const char *DOC_DESCRIPTION = R"(
     Returns if two POINT_2D's are within a target distance in meters, using an ellipsoidal model of the earths surface
+
+	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 distance is returned in meters. This function uses the [GeographicLib](https://geographiclib.sourceforge.io/) library to solve the [inverse geodesic problem](https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid#Solution_of_the_direct_and_inverse_problems), calculating the distance between two points using an ellipsoidal model of the earth. This is a highly accurate method for calculating the distance between two arbitrary points taking the curvature of the earths surface into account, but is also the slowest.
 )";
 
 static constexpr const char *DOC_EXAMPLE = R"(

spatial/src/spatial/geos/functions/scalar/st_buffer.cpp

@@ -101,7 +101,7 @@ static constexpr const char *DOC_DESCRIPTION = R"(
 
     `cap_style` must be one of "CAP_ROUND", "CAP_FLAT", "CAP_SQUARE". This parameter is case-insensitive.
 
-    `mite_limit` only applies when `join_style` is "JOIN_MITRE". It is the ratio of the distance from the corner to the miter point to the corner radius. The default value is 1.0.
+    `mitre_limit` only applies when `join_style` is "JOIN_MITRE". It is the ratio of the distance from the corner to the mitre point to the corner radius. The default value is 1.0.
 
     This is a planar operation and will not take into account the curvature of the earth.
 )";

spatial/src/spatial/proj/functions.cpp

@@ -437,7 +437,7 @@ Transforms a geometry between two coordinate systems
 
 The source and target coordinate systems can be specified using any format that the [PROJ library](https://proj.org) supports.
 
-The optional `always_xy` parameter can be used to force the input and output geometries to be interpreted as having a [northing, easting] coordinate axis order regardless of what the source and target coordinate system definition says. This is particularly useful when transforming to/from the [WGS84/EPSG:4326](https://en.wikipedia.org/wiki/World_Geodetic_System) coordinate system (what most people think of when they hear "longitude"/"latitude" or "GPS coordinates"), which is defined as having a [latitude, longitude] axis order even though [longitude, latitude] is commonly used in practice (e.g. in [GeoJSON](https://tools.ietf.org/html/rfc7946)). More details available in the [PROJ documentation](https://proj.org/en/9.3/faq.html#why-is-the-axis-ordering-in-proj-not-consistent).
+The third optional `always_xy` parameter can be used to force the input and output geometries to be interpreted as having a [easting, northing] coordinate axis order regardless of what the source and target coordinate system definition says. This is particularly useful when transforming to/from the [WGS84/EPSG:4326](https://en.wikipedia.org/wiki/World_Geodetic_System) coordinate system (what most people think of when they hear "longitude"/"latitude" or "GPS coordinates"), which is defined as having a [latitude, longitude] axis order even though [longitude, latitude] is commonly used in practice (e.g. in [GeoJSON](https://tools.ietf.org/html/rfc7946)). More details available in the [PROJ documentation](https://proj.org/en/9.3/faq.html#why-is-the-axis-ordering-in-proj-not-consistent).
 
 DuckDB spatial vendors its own static copy of the PROJ database of coordinate systems, so if you have your own installation of PROJ on your system the available coordinate systems may differ to what's available in other GIS software.
 )";
@@ -446,7 +446,7 @@ static constexpr const char *DOC_EXAMPLE = R"(
 -- Transform a geometry from EPSG:4326 to EPSG:3857 (WGS84 to WebMercator)
 -- Note that since WGS84 is defined as having a [latitude, longitude] axis order
 -- we follow the standard and provide the input geometry using that axis order,
--- but the output will be [northing, easting] because that is what's defined by
+-- but the output will be [easting, northing] because that is what's defined by
 -- WebMercator.
 
 SELECT ST_AsText(
@@ -463,7 +463,7 @@ POINT (544615.0239773799 6867874.103539125)
 -- which uses WGS84 but with [longitude, latitude] axis order. We can use the
 -- `always_xy` parameter to force the input geometry to be interpreted as having
 -- a [northing, easting] axis order instead, even though the source coordinate
--- system definition says otherwise.
+-- reference system definition (WGS84) says otherwise.
 
 SELECT ST_AsText(
     ST_Transform(