Generate device options (Koenkk#989)

* Add device options generator

* Temp code to remove device specific configuration

* Small update for: Temp code to remove device specific configuration

* Run docgen only: removes all device type specific configuration

* Enable generate options code and remove temp code

* Run docgen only: generate options

* Custom notes

docgen/device_page_options.ts

@@ -0,0 +1,46 @@
+import { strict as assert } from 'assert';
+
+function addTrailingDot(text: string) {
+  text = text.trim();
+  return text.endsWith('.') || text.endsWith('`') ? text : text + '.';
+}
+
+export function generateOptions(definition) {
+  if (definition.options.length == 0) return '';
+  return `
+## Options
+*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
+
+${definition.options.map((e) => getOptionDocs(e)).join('\n\n')}
+`;
+}
+
+function getOptionDocs(option) {
+  let extra = null;
+
+  if (option.type === 'numeric') {
+    extra = 'The value must be a number';
+    if (option.value_min != null) extra += ` with a minimum value of \`${option.value_min}\``;
+    if (option.value_min != null && option.value_max != null) extra += ` and with a`
+    if (option.value_max != null) extra += ` with a maximum value of \`${option.value_max}\``;
+  } else if (option.type === 'binary') {
+    extra = `The value must be \`${option.value_on}\` or \`${option.value_off}\``;
+  } else if (option.type === 'enum') {
+    extra = `The value must be one of ${option.values.map(v => `\`${v}\``).join(', ')}`;
+  } else if (option.type === 'list') {
+    extra = `The value must be a list of ${option.item_type}`;
+  } else if (option.type === 'composite' && option.property === 'simulated_brightness') {
+    extra = `Example:
+\`\`\`yaml
+simulated_brightness:
+  delta: 20 # delta per interval, default = 20
+  interval: 200 # interval in milliseconds, default = 200
+\`\`\`
+`
+  }
+
+  assert(extra != null, `No option doc generator for '${JSON.stringify(option)}'`);
+
+  return `* \`${option.property}\`: ${addTrailingDot(option.description)} ${addTrailingDot(extra)}`
+}
+

docgen/generate_device.ts

@@ -5,6 +5,7 @@ import * as path from "path";
 import { promises as fsp } from "fs";
 import { generatePage, getAddedAt, getImage, normalizeModel } from "./utils";
 import { generateExpose } from "./device_page_exposes";
+import { generateOptions } from "./device_page_options";
 import { devicesBaseDir, imageBaseDir, imageBaseUrl } from "./constants";
 
 export function resolveDeviceFile(model) {
@@ -71,6 +72,7 @@ ${ device.hasOwnProperty('ota') ? `
 ## OTA updates
 This device supports OTA updates, for more information see [OTA updates](../guide/usage/ota_updates.md).
 ` : '' }
+${ generateOptions(device) }
 ${ generateExpose(device) }
 `;
 

docs/devices/0140302.md

@@ -23,17 +23,17 @@ pageClass: device-page
 
 
 <!-- Notes BEGIN: You can edit here. Add "## Notes" headline if not already present. -->
-## Notes
 
-### Device type specific configuration
-*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
 
-* `transition`: Controls the transition time (in seconds) of on/off, brightness,
-color temperature (if applicable) and color (if applicable) changes. Defaults to `0` (no transition).
-Note that this value is overridden if a `transition` value is present in the MQTT command payload.
 <!-- Notes END: Do not edit below this line -->
 
 
+## Options
+*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
+
+* `transition`: Controls the transition time (in seconds) of on/off, brightness, color temperature (if applicable) and color (if applicable) changes. Defaults to `0` (no transition). The value must be a number with a minimum value of `0`
+
+
 ## Exposes
 
 ### Light 

docs/devices/014G2461.md

@@ -35,17 +35,13 @@ To factory reset:
 * Remove one battery.
 * Press and hold "o" button.
 * Insert battery and hold button pressed for about 3 seconds (display will flash all symbols).
-
-### Device type specific configuration
-*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
-
-* `legacy`: Set to `false` to disable the legacy integration (highly recommended!) (default: true)
 <!-- Notes END: Do not edit below this line -->
 
 ## OTA updates
 This device supports OTA updates, for more information see [OTA updates](../guide/usage/ota_updates.md).
 
 
+
 ## Exposes
 
 ### Battery (numeric)

docs/devices/0402946.md

@@ -37,20 +37,6 @@ Lock will now reset the Zigbee module and go to pairing mode
 ### PIN Code Usage
 To retrieve the state, send a `get` message to the device topic (`zigbee2mqtt/DEVICE_FRIENDLY_NAME/get`) with the body `{"pin_code":{"user":1}}`. To set, send a `set` message to the device topic (`zigbee2mqtt/DEVICE_FRIENDLY_NAME/set`) with the body `{"pin_code":{"user":1,"pin_code":1234}}`. To clear a code, send a `set` message with the body `{"pin_code":{"user":1}}`
 
-### Device type specific configuration
-*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
-
-* `expose_pin`: Allows to retrieve the `pin_code` value, rather than just user status (`available`/`enabled`), for `pin_code` endpoints (default: `false`) in `devices.yaml`.
-
-Example:
-
-```yaml
-'0x680ae2fffe6bb522':
-  friendly_name: '0x680ae2fffe6bb522'
-  expose_pin: true
-```
-
-
 ### Manual
 [ID LOCK 150 user manual](https://idlock.no/wp-content/uploads/2018/03/20180123-001-IDL150-UserManual.pdf)
 [Zigbee module user manual](https://idlock.no/wp-content/uploads/2020/11/User-Manual-Zigbee-module_EN_v0.4.pdf)
@@ -60,6 +46,12 @@ Example:
 <!-- Notes END: Do not edit below this line -->
 
 
+## Options
+*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
+
+* `expose_pin`: Expose pin of this lock in the published payload (default false). The value must be `true` or `false`
+
+
 ## Exposes
 
 ### Lock 

docs/devices/046677476816.md

@@ -87,19 +87,18 @@ Rules:
 - When setting `hue_power_on_behavior` = `on`, any not provided values will be reset to their factory defaults
 
 Note: if `hue_power_on_behavior` is set to `off`, then the only way to turn the bulb on will be through a paired smart device (see pairing above). You will NOT be able to turn the bulb on by sequentially switching power on and off.
-
-### Device type specific configuration
-*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
-
-* `transition`: Controls the transition time (in seconds) of on/off, brightness,
-color temperature (if applicable) and color (if applicable) changes. Defaults to `0` (no transition).
-Note that this value is overridden if a `transition` value is present in the MQTT command payload.
 <!-- Notes END: Do not edit below this line -->
 
 ## OTA updates
 This device supports OTA updates, for more information see [OTA updates](../guide/usage/ota_updates.md).
 
 
+## Options
+*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
+
+* `transition`: Controls the transition time (in seconds) of on/off, brightness, color temperature (if applicable) and color (if applicable) changes. Defaults to `0` (no transition). The value must be a number with a minimum value of `0`
+
+
 ## Exposes
 
 ### Light 

docs/devices/046677551780.md

@@ -87,19 +87,18 @@ Rules:
 - When setting `hue_power_on_behavior` = `on`, any not provided values will be reset to their factory defaults
 
 Note: if `hue_power_on_behavior` is set to `off`, then the only way to turn the bulb on will be through a paired smart device (see pairing above). You will NOT be able to turn the bulb on by sequentially switching power on and off.
-
-### Device type specific configuration
-*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
-
-* `transition`: Controls the transition time (in seconds) of on/off, brightness,
-color temperature (if applicable) and color (if applicable) changes. Defaults to `0` (no transition).
-Note that this value is overridden if a `transition` value is present in the MQTT command payload.
 <!-- Notes END: Do not edit below this line -->
 
 ## OTA updates
 This device supports OTA updates, for more information see [OTA updates](../guide/usage/ota_updates.md).
 
 
+## Options
+*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
+
+* `transition`: Controls the transition time (in seconds) of on/off, brightness, color temperature (if applicable) and color (if applicable) changes. Defaults to `0` (no transition). The value must be a number with a minimum value of `0`
+
+
 ## Exposes
 
 ### Light 

docs/devices/046677552343.md

@@ -59,6 +59,7 @@ Note: if `hue_power_on_behavior` is set to `off`, then the only way to turn the
 This device supports OTA updates, for more information see [OTA updates](../guide/usage/ota_updates.md).
 
 
+
 ## Exposes
 
 ### Switch 

docs/devices/064873.md

@@ -28,6 +28,7 @@ pageClass: device-page
 <!-- Notes END: Do not edit below this line -->
 
 
+
 ## Exposes
 
 ### Battery (numeric)

docs/devices/064888.md

@@ -28,6 +28,7 @@ pageClass: device-page
 <!-- Notes END: Do not edit below this line -->
 
 
+
 ## Exposes
 
 ### Switch 

docs/devices/067646.md

@@ -28,6 +28,7 @@ pageClass: device-page
 <!-- Notes END: Do not edit below this line -->
 
 
+
 ## Exposes
 
 ### Battery (numeric)

docs/devices/067694.md

@@ -31,6 +31,7 @@ The remote supports [binding](../guide/usage/binding.md) for toggle action.
 <!-- Notes END: Do not edit below this line -->
 
 
+
 ## Exposes
 
 ### Battery (numeric)

docs/devices/067771.md

@@ -25,14 +25,6 @@ pageClass: device-page
 <!-- Notes BEGIN: You can edit here. Add "## Notes" headline if not already present. -->
 ## Notes
 
-### Device type specific configuration
-*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
-
-* `transition`: Controls the transition time (in seconds) of on/off, brightness,
-color temperature (if applicable) and color (if applicable) changes. Defaults to `0` (no transition).
-Note that this value is overridden if a `transition` value is present in the MQTT command payload.
-
-
 ### Model numbers
 Model number depends on the country and the colour of the devices, for instance:
 
@@ -108,6 +100,12 @@ Example of MQTT message payload to Identify the switch. This should be sent to `
 <!-- Notes END: Do not edit below this line -->
 
 
+## Options
+*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
+
+* `transition`: Controls the transition time (in seconds) of on/off, brightness, color temperature (if applicable) and color (if applicable) changes. Defaults to `0` (no transition). The value must be a number with a minimum value of `0`
+
+
 ## Exposes
 
 ### Light 

docs/devices/067773.md

@@ -39,12 +39,6 @@ To disable the legacy integration add the following to your `configuration.yaml`
 ```
 
 
-### Device type specific configuration
-*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
-
-* `legacy`: Set to `false` to disable the legacy integration (highly recommended!) (default: true)
-
-
 ### Model numbers
 Model number depends on the country and the colour of the devices.
 French models are branded as Céliane with Netatmo, and models for this device depends on the colour, with the following numbers: "0 677 23", "0 677 73", and "0 648 93".
@@ -55,6 +49,12 @@ The remote supports [binding](../guide/usage/binding.md).
 <!-- Notes END: Do not edit below this line -->
 
 
+## Options
+*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
+
+* `legacy`: Set to false to disable the legacy integration (highly recommended), will change structure of the published payload (default true). The value must be `true` or `false`
+
+
 ## Exposes
 
 ### Battery (numeric)

docs/devices/067774.md

@@ -25,20 +25,6 @@ pageClass: device-page
 <!-- Notes BEGIN: You can edit here. Add "## Notes" headline if not already present. -->
 ## Notes
 
-### Device type specific configuration
-*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
-
-* `simulated_brightness`: Set to `true` to simulate a `brightness` value (default: `false`).
-If this device provides a `brightness_move_up` or `brightness_move_down` action it is possible to specify the update
-interval and delta. This can be done by instead of specifying `true`:
-
-```yaml
-simulated_brightness:
-  delta: 20 # delta per interval, default = 20
-  interval: 200 # interval in milliseconds, default = 200
-```
-
-
 ### Model numbers
 Model number depends on the country and the colour of the devices. For example:
 - French models are branded as Céliane with Netatmo, and models for this device depends on the colour, with the following numbers: "0 677 24", "0 677 74", and "0 677 94".
@@ -49,6 +35,17 @@ The remote supports [binding](../guide/usage/binding.md) on each endpoint, so yo
 <!-- Notes END: Do not edit below this line -->
 
 
+## Options
+*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
+
+* `simulated_brightness`: Simulate a brightness value. If this device provides a brightness_move_up or brightness_move_down action it is possible to specify the update interval and delta. Example:
+```yaml
+simulated_brightness:
+  delta: 20 # delta per interval, default = 20
+  interval: 200 # interval in milliseconds, default = 200
+```
+
+
 ## Exposes
 
 ### Battery (numeric)

docs/devices/067775_741811.md

@@ -28,6 +28,7 @@ pageClass: device-page
 <!-- Notes END: Do not edit below this line -->
 
 
+
 ## Exposes
 
 ### Switch 

docs/devices/067776.md

@@ -25,19 +25,19 @@ pageClass: device-page
 <!-- Notes BEGIN: You can edit here. Add "## Notes" headline if not already present. -->
 ## Notes
 
-### Device type specific configuration
-*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
-
-* `invert_cover`: By default the position/tilt values mean: open = 100, closed = 0. This can be inverted by setting this option to true (so open = 0, close = 100).
-
-
 ### Model number
 Model number depends on the country and the colour of the devices.
 French models are branded as Céliane with Netatmo, and models for this device depends on the colour, with the following numbers: "0 677 26", "0 677 76" and "0 648 96".
 Spanish models are branded as Legrand Valena Next, and models for this device depends on the colour, with the following numbers: "7 418 07", "7 418 37" and "7 418 67".
 <!-- Notes END: Do not edit below this line -->
 
 
+## Options
+*[How to use device type specific configuration](../guide/configuration/devices-groups.md#specific-device-options)*
+
+* `invert_cover`: Inverts the cover position, false: open=100,close=0, true: open=0,close=100 (default false). The value must be `true` or `false`
+
+
 ## Exposes
 
 ### Cover