docs(external): add docs for haversine VRL function (vectordotdev#23336)

* docs(external): add docs for `haversine` VRL function

Related: vectordotdev/vrl#1442

* Apply suggestions from code review

Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com>

* Rename haversine function in docs

* Add map category to docs

* Fix docs formatting

* Generate #FunctionCategory disjunction from list to reduce duplication

* Update names of arguments

* Update VRL

* Update VRL

* Update types for haversine in docs

---------

Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com>
Co-authored-by: Pavlos Rontidis <pavlos.rontidis@gmail.com>

Author: 3 people

Cargo.lock

@@ -28,10 +28,6 @@ remap: {
 		pure:       bool | *true
 	}
 
-	#FunctionCategory: "Array" | "Codec" | "Coerce" | "Convert" | "Debug" | "Enrichment" | "Enumerate" | "Event" | "Path" | "Cryptography" | "IP" | "Number" | "Object" | "Parse" | "Random" | "String" | "System" | "Timestamp" | "Type" | "Checksum"
-
-	// A helper array for generating docs. At some point, we should generate this from the
-	// #FunctionCategory enum if CUE adds support for that.
 	function_categories: [
 		"Array",
 		"Codec",
@@ -44,6 +40,7 @@ remap: {
 		"Path",
 		"Cryptography",
 		"IP",
+		"Map",
 		"Number",
 		"Object",
 		"Parse",
@@ -55,6 +52,8 @@ remap: {
 		"Checksum",
 	]
 
+	#FunctionCategory: or(function_categories)
+
 	functions: [Name=string]: #Function & {
 		name: Name
 	}

website/cue/reference/remap/functions.cue

@@ -0,0 +1,72 @@
+package metadata
+
+remap: functions: haversine: {
+	category:    "Map"
+	description: """
+		Calculates [haversine](\(urls.haversine)) distance and bearing between two points.
+		Results are available in kilometers or miles.
+		"""
+
+	arguments: [
+		{
+			name:        "latitude1"
+			description: "Latitude of the first point."
+			required:    true
+			type: ["float"]
+		},
+		{
+			name:        "longitude1"
+			description: "Longitude of the first point."
+			required:    true
+			type: ["float"]
+		},
+		{
+			name:        "latitude2"
+			description: "Latitude of the second point."
+			required:    true
+			type: ["float"]
+		},
+		{
+			name:        "longitude2"
+			description: "Longitude of the second point."
+			required:    true
+			type: ["float"]
+		},
+		{
+			name:        "measurement"
+			description: "Measurement system to use for resulting distance."
+			required:    false
+			type: ["string"]
+			default: "kilometers"
+			enum: {
+				kilometers: "Use kilometers for the resulting distance."
+				miles:      "Use miles for the resulting distance."
+			}
+		},
+	]
+	internal_failure_reasons: []
+	return: types: ["object"]
+
+	examples: [
+		{
+			title: "Haversine in kilometers"
+			source: #"""
+				haversine(0.0, 0.0, 10.0, 10.0)
+				"""#
+			return: {
+				distance: 1568.5227233
+				bearing:  44.561
+			}
+		},
+		{
+			title: "Haversine in miles"
+			source: #"""
+				haversine(0.0, 0.0, 10.0, 10.0, "miles")
+				"""#
+			return: {
+				distance: 974.6348468
+				bearing:  44.561
+			}
+		},
+	]
+}

website/cue/reference/remap/functions/haversine.cue

@@ -246,6 +246,7 @@ urls: {
 	grok_patterns:                              "\(github)/daschl/grok/tree/master/patterns"
 	gzip:                                       "https://www.gzip.org/"
 	haproxy:                                    "https://www.haproxy.org/"
+	haversine:                                  "\(wikipedia)/wiki/Haversine_formula"
 	helm:                                       "https://helm.sh/"
 	heroku:                                     "https://www.heroku.com"
 	heroku_http_log_drain:                      "https://devcenter.heroku.com/articles/log-drains#https-drains"