Chore: regenerate docs

2025-04-08 02:38:44 +02:00 · 2025-04-08 02:38:44 +02:00 · e997653284
commit e997653284
parent aa373ee698
91 changed files with 3055 additions and 1061 deletions
--- a/Docs/builtin_units.md
+++ b/Docs/builtin_units.md
@ -4,30 +4,94 @@

 ## Table of contents

-1. [power](#power)
-  - [MW](#mw)
-  - [kW](#kw)
-  - [W](#w)
-  - [GW](#gw)
-2. [voltage](#voltage)
-  - [V](#v)
-3. [current](#current)
-  - [A](#a)
-4. [distance](#distance)
-  - [m](#m)
-  - [cm](#cm)
-  - [mm](#mm)
-  - [ft](#ft)
-5. [speed](#speed)
-  - [kmh](#kmh)
-  - [mph](#mph)
-6. [duration](#duration)
-  - [minutes](#minutes)
-  - [hours](#hours)
-  - [days](#days)
-  - [weeks](#weeks)
-  - [months](#months)
-  - [years](#years)
+1. [Units](#units)
+  - [How to use](#how-to-use)
+2. [Rendering](#rendering)
+3. [Usage](#usage)
+  - [unit](#unit)
+    + [power](#power)
+       * [MW](#mw)
+       * [kW](#kw)
+       * [W](#w)
+       * [GW](#gw)
+    + [voltage](#voltage)
+       * [V](#v)
+    + [current](#current)
+       * [A](#a)
+    + [distance](#distance)
+       * [m](#m)
+       * [cm](#cm)
+       * [mm](#mm)
+       * [ft](#ft)
+    + [speed](#speed)
+       * [kmh](#kmh)
+       * [mph](#mph)
+    + [duration](#duration)
+       * [minutes](#minutes)
+       * [hours](#hours)
+       * [days](#days)
+       * [weeks](#weeks)
+       * [months](#months)
+       * [years](#years)
+
+## How to use
+
+In some cases, a value is represented in a certain unit (such as meters for heigt/distance/..., km/h for speed, ...)
+
+Sometimes, multiple denominations are possible (e.g. km/h vs mile/h; megawatt vs kilowatt vs gigawatt for power generators, ...)
+
+This brings in some troubles, as there are multiple ways to write it (no denomitation, 'm' vs 'meter' 'metre', ...)
+
+Not only do we want to write consistent data to OSM, we also want to present this consistently to the user.
+This is handled by defining units.
+
+# Rendering
+
+To render a value with long (human) denomination, use {canonical(key)}
+
+# Usage
+
+First of all, you define which keys have units applied, for example:
+
+```
+units: [
+ appliesTo: ["maxspeed", "maxspeed:hgv", "maxspeed:bus"]
+ applicableUnits: [
+     ...
+ ]
+]
+```
+
+ApplicableUnits defines which is the canonical extension, how it is presented to the user, ...:
+
+```
+applicableUnits: [
+{
+    canonicalDenomination: "km/h",
+    alternativeDenomination: ["km/u", "kmh", "kph"]
+    default: true,
+    human: {
+        en: "kilometer/hour",
+        nl: "kilometer/uur"
+    },
+    humanShort: {
+        en: "km/h",
+        nl: "km/u"
+    }
+},
+{
+    canoncialDenomination: "mph",
+    ... similar for miles an hour ...
+}
+]
+```
+
+If this is defined, then every key which the denominations apply to (`maxspeed`, `maxspeed:hgv` and `maxspeed:bus`) will be rewritten at the metatagging stage:
+every value will be parsed and the canonical extension will be added add presented to the other parts of the code.
+
+Also, if a freeform text field is used, an extra dropdown with applicable denominations will be given
+
+Units 

 ## unit

@ -177,4 +241,4 @@ Alternative denominations:
 #### years


-This document is autogenerated from [assets/layers/unit/unit.json](https://source.mapcomplete.org/MapComplete/MapComplete/src/branch/develop/assets/layers/unit/unit.json)
+This document is autogenerated from [assets/layers/unit/unit.json](https://source.mapcomplete.org/MapComplete/MapComplete/src/branch/develop/assets/layers/unit/unit.json), [src/Models/ThemeConfig/Json/UnitConfigJson.ts](https://source.mapcomplete.org/MapComplete/MapComplete/src/branch/develop/src/Models/ThemeConfig/Json/UnitConfigJson.ts)