Use the new style for configuration variables description

fabaff commented 5 years ago

A while back an advance way to describe the configuration variables was introduced.

{% configuration %}
api_key:
  description: The API key to access the service.
  required: true
  type: string
name:
  description: Name to use in the frontend.
  required: false
  default: The default name to use in the frontend.
  type: string
{% endconfiguration %}

At the moment not all platform and component documentation is ported to the new style.

This the tracking issue. Please don't close but add as a reference to your Pull request.

WofWca commented 5 years ago

Should we open individual PRs for each page changed?

fabaff commented 5 years ago

Yes, please or at least don't add 50 platforms to one Pull Request. If you want you can combine the changes for a component and its platforms.

If the Pull Requests are small it easier to spot for others which docs are in progress or already done.

WofWca commented 5 years ago

I think that the documentation, in accordance to which these changes must be done, is a bit outdated. home-assistant/developers.home-assistant#104

fabaff commented 5 years ago

@WofWca, Doc were updated. Please feel free to improve them if you think that something is not clear.. Thanks for the feedback, BTW.

WofWca commented 5 years ago

Opened a new issue home-assistant/developers.home-assistant#107

datafx commented 5 years ago

How would we handle this for something like modbus which has different required configuration variables depending whether you are using tcp or serial communication? Right now, the component actually has two different configuration variable sections.

tjorim commented 5 years ago

I'm currently checking all components. Here's a working list while I'm going through them.

Components I'm currently updating:

[ ] alarmdecoder.markdown
[x] binary_sensor.bayesian.markdown
[x] binary_sensor.gc100.markdown
[x] binary_sensor.rpi_gpio.markdown
[x] binary_sensor.rpi_pfio.markdown
[ ] calendar.todoist.markdown
[ ] climate.eq3btsmart.markdown
[ ] climate.generic_thermostat.markdown
[ ] climate.knx.markdown
[ ] climate.proliphix.markdown
[ ] cover.command_line.markdown

Components that needs to be updated:

[ ] cover.rflink.markdown
[ ] cover.rpi_gpio.markdown
[ ] demo.markdown
[ ] switch.snmp
[ ] switch.pilight

Components that have not been checked yet. They have been checked to see if they contain {% configuration %}, which they don't. But they might just as well don't have a configuration section.

[ ] device_tracker.bmw_connected_drive.markdown
[ ] device_tracker.huawei_lte.markdown
[ ] device_tracker.locative.markdown
[ ] device_tracker.markdown
[ ] device_tracker.mercedesme.markdown
[ ] device_tracker.mysensors.markdown
[ ] device_tracker.openwrt.markdown
[ ] device_tracker.owntracks_http.markdown
[ ] device_tracker.tesla.markdown
[ ] device_tracker.volvooncall.markdown
[ ] dialogflow.markdown
[ ] discoverable.markdown
[ ] discovery.markdown
[ ] duckdns.markdown
[ ] envisalink.markdown
[ ] eufy.markdown
[ ] fan.comfoconnect.markdown
[ ] fan.dyson.markdown
[ ] fan.insteon.markdown
[ ] fan.isy994.markdown
[ ] fan.markdown
[ ] fan.tuya.markdown
[ ] fan.wink.markdown
[ ] fan.zha.markdown
[ ] fan.zwave.markdown
[ ] geo_location.markdown
[ ] hdmi_cec.markdown
[ ] homekit_controller.markdown
[ ] ifttt.manything.markdown
[ ] ifttt.markdown
[ ] image_processing.dlib_face_identify.markdown
[ ] image_processing.markdown
[ ] image_processing.opencv.markdown
[ ] image_processing.seven_segments.markdown
[ ] insteon.markdown
[ ] insteon_local.markdown
[ ] insteon_plm.markdown
[ ] intent_script.markdown
[ ] introduction.markdown
[ ] ios.markdown
[ ] isy994.markdown
[ ] keyboard.markdown
[ ] keyboard_remote.markdown
[ ] lametric.markdown
[ ] light.abode.markdown
[ ] light.avion.markdown
[ ] light.blinkt.markdown
[ ] light.deconz.markdown
[ ] light.eufy.markdown
[ ] light.hive.markdown
[ ] light.homekit_controller.markdown
[ ] light.homematic.markdown
[ ] light.homematicip_cloud.markdown
[ ] light.hue.markdown
[ ] light.insteon.markdown
[ ] light.isy994.markdown
[ ] light.limitlessled.markdown
[ ] light.litejet.markdown
[ ] light.lutron.markdown
[ ] light.lutron_caseta.markdown
[ ] light.markdown
[ ] light.mysensors.markdown
[ ] light.piglow.markdown
[ ] light.qwikswitch.markdown
[ ] light.rflink.markdown
[ ] light.rpi_gpio_pwm.markdown
[ ] light.scsgate.markdown
[ ] light.sensehat.markdown
[ ] light.sisyphus.markdown
[ ] light.skybell.markdown
[ ] light.tellstick.markdown
[ ] light.tikteck.markdown
[ ] light.tradfri.markdown
[ ] light.tuya.markdown
[ ] light.vera.markdown
[ ] light.wemo.markdown
[ ] light.wink.markdown
[ ] light.x10.markdown
[ ] light.xiaomi_aqara.markdown
[ ] light.yeelightsunflower.markdown
[ ] light.zengge.markdown
[ ] light.zha.markdown
[ ] light.zwave.markdown
[ ] lirc.markdown
[ ] litejet.markdown
[ ] lock.abode.markdown
[ ] lock.august.markdown
[ ] lock.bmw_connected_drive.markdown
[ ] lock.homematic.markdown
[ ] lock.isy994.markdown
[ ] lock.lockitron.markdown
[ ] lock.markdown
[ ] lock.tesla.markdown
[ ] lock.vera.markdown
[ ] lock.verisure.markdown
[ ] lock.wink.markdown
[ ] lock.xiaomi_aqara.markdown
[ ] lock.zwave.markdown
[ ] mailbox.asterisk_cdr.markdown
[ ] mailbox.asterisk_mbox.markdown
[ ] mailbox.markdown
[ ] map.markdown
[ ] media_extractor.markdown
[ ] media_player.apple_tv.markdown
[ ] media_player.denonavr.markdown
[ ] media_player.gstreamer.markdown
[ ] media_player.markdown
[ ] media_player.monoprice.markdown
[ ] media_player.nad.markdown
[ ] media_player.nadtcp.markdown
[ ] media_player.openhome.markdown
[ ] media_player.panasonic_viera.markdown
[ ] media_player.pandora.markdown
[ ] media_player.philips_js.markdown
[ ] media_player.pioneer.markdown
[ ] media_player.russound_rio.markdown
[ ] media_player.russound_rnet.markdown
[ ] media_player.sisyphus.markdown
[ ] media_player.snapcast.markdown
[ ] media_player.soundtouch.markdown
[ ] media_player.squeezebox.markdown
[ ] media_player.volumio.markdown
[ ] mercedesme.markdown
[ ] mqtt.markdown
[ ] mqtt_statestream.markdown
[ ] notify.apns.markdown
[ ] notify.aws_lambda.markdown
[ ] notify.aws_sns.markdown
[ ] notify.aws_sqs.markdown
[ ] notify.ciscospark.markdown
[ ] notify.clickatell.markdown
[ ] notify.clicksend_tts.markdown
[ ] notify.command_line.markdown
[ ] notify.facebook.markdown
[ ] notify.file.markdown
[ ] notify.gntp.markdown
[ ] notify.group.markdown
[ ] notify.hipchat.markdown
[ ] notify.instapush.markdown
[ ] notify.joaoapps_join.markdown
[ ] notify.kodi.markdown
[ ] notify.lannouncer.markdown
[ ] notify.llamalab_automate.markdown
[ ] notify.markdown
[ ] notify.matrix.markdown
[ ] notify.message_bird.markdown
[ ] notify.mqtt.markdown
[ ] notify.mycroft.markdown
[ ] notify.mysensors.markdown
[ ] notify.nfandroidtv.markdown
[ ] notify.prowl.markdown
[ ] notify.pushbullet.markdown
[ ] notify.pushetta.markdown
[ ] notify.pushover.markdown
[ ] notify.pushsafer.markdown
[ ] notify.rest.markdown
[ ] notify.rocketchat.markdown
[ ] notify.sendgrid.markdown
[ ] notify.slack.markdown
[ ] notify.smtp.markdown
[ ] notify.syslog.markdown
[ ] notify.tibber.markdown
[ ] notify.xmpp.markdown
[ ] notify.yessssms.markdown
[ ] nuimo_controller.markdown
[ ] panel_custom.markdown
[ ] persistent_notification.markdown
[ ] pilight.markdown
[ ] plant.markdown
[ ] prometheus.markdown
[ ] proximity.markdown
[ ] python_script.markdown
[ ] qwikswitch.markdown
[ ] rachio.markdown
[ ] raspihats.markdown
[ ] remote.apple_tv.markdown
[ ] remote.itach.markdown
[ ] remote.kira.markdown
[ ] remote.markdown
[ ] rest_command.markdown
[ ] rflink.markdown
[ ] rpi_gpio.markdown
[ ] rpi_pfio.markdown
[ ] rss_feed_template.markdown
[ ] satel_integra.markdown
[ ] scene.deconz.markdown
[ ] scene.litejet.markdown
[ ] scene.lutron_caseta.markdown
[ ] scene.tahoma.markdown
[ ] scene.tuya.markdown
[ ] scene.velux.markdown
[ ] scene.vera.markdown
[ ] scene.wink.markdown
[ ] script.markdown
[ ] scsgate.markdown
[ ] sensor.abode.markdown
[ ] sensor.alarmdecoder.markdown
[ ] sensor.amcrest.markdown
[ ] sensor.android_ip_webcam.markdown
[ ] sensor.apcupsd.markdown
[ ] sensor.api_streams.markdown
[ ] sensor.arest.markdown
[ ] sensor.arlo.markdown
[ ] sensor.arwn.markdown
[ ] sensor.bh1750.markdown
[ ] sensor.blink.markdown
[ ] sensor.bme280.markdown
[ ] sensor.bmw_connected_drive.markdown
[ ] sensor.broadlink.markdown
[ ] sensor.buienradar.markdown
[ ] sensor.canary.markdown
[ ] sensor.coinbase.markdown
[ ] sensor.comed_hourly_pricing.markdown
[ ] sensor.comfoconnect.markdown
[ ] sensor.crimereports.markdown
[ ] sensor.darksky.markdown
[ ] sensor.deconz.markdown
[ ] sensor.dnsip.markdown
[ ] sensor.dte_energy_bridge.markdown
[ ] sensor.dublin_bus_transport.markdown
[ ] sensor.dweet.markdown
[ ] sensor.dyson.markdown
[ ] sensor.ebox.markdown
[ ] sensor.ecobee.markdown
[ ] sensor.eddystone_temperature.markdown
[ ] sensor.edp_redy.markdown
[ ] sensor.efergy.markdown
[ ] sensor.eight_sleep.markdown
[ ] sensor.eliqonline.markdown
[ ] sensor.emoncms.markdown
[ ] sensor.envirophat.markdown
[ ] sensor.envisalink.markdown
[ ] sensor.fastdotcom.markdown
[ ] sensor.fedex.markdown
[ ] sensor.fido.markdown
[ ] sensor.file.markdown
[ ] sensor.fitbit.markdown
[ ] sensor.fritzbox_callmonitor.markdown
[ ] sensor.fritzbox_netmonitor.markdown
[ ] sensor.geizhals.markdown
[ ] sensor.google_travel_time.markdown
[ ] sensor.gtfs.markdown
[ ] sensor.habitica.markdown
[ ] sensor.history_stats.markdown
[ ] sensor.hive.markdown
[ ] sensor.homematic.markdown
[ ] sensor.homematicip_cloud.markdown
[ ] sensor.hp_ilo.markdown
[ ] sensor.http.markdown
[ ] sensor.htu21d.markdown
[ ] sensor.huawei_lte.markdown
[ ] sensor.hydroquebec.markdown
[ ] sensor.influxdb.markdown
[ ] sensor.insteon.markdown
[ ] sensor.ios.markdown
[ ] sensor.iota.markdown
[ ] sensor.irish_rail_transport.markdown
[ ] sensor.isy994.markdown
[ ] sensor.juicenet.markdown
[ ] sensor.kira.markdown
[ ] sensor.kwb.markdown
[ ] sensor.logi_circle.markdown
[ ] sensor.london_air.markdown
[ ] sensor.london_underground.markdown
[ ] sensor.loopenergy.markdown
[ ] sensor.lyft.markdown
[ ] sensor.markdown
[ ] sensor.melissa.markdown
[ ] sensor.mercedesme.markdown
[ ] sensor.mfi.markdown
[ ] sensor.mhz19.markdown
[ ] sensor.min_max.markdown
[ ] sensor.moon.markdown
[ ] sensor.mqtt_room.markdown
[ ] sensor.mvglive.markdown
[ ] sensor.mychevy.markdown
[ ] sensor.mysensors.markdown
[ ] sensor.nederlandse_spoorwegen.markdown
[ ] sensor.neurio_energy.markdown
[ ] sensor.ohmconnect.markdown
[ ] sensor.openevse.markdown
[ ] sensor.opensky.markdown
[ ] sensor.openuv.markdown
[ ] sensor.otp.markdown
[ ] sensor.pilight.markdown
[ ] sensor.pocketcasts.markdown
[ ] sensor.pushbullet.markdown
[ ] sensor.pvoutput.markdown
[ ] sensor.qnap.markdown
[ ] sensor.qwikswitch.markdown
[ ] sensor.rainbird.markdown
[ ] sensor.rainmachine.markdown
[ ] sensor.rflink.markdown
[ ] sensor.sabnzbd.markdown
[ ] sensor.scrape.markdown
[ ] sensor.sensehat.markdown
[ ] sensor.sleepiq.markdown
[ ] sensor.sma.markdown
[ ] sensor.smappee.markdown
[ ] sensor.statistics.markdown
[ ] sensor.tado.markdown
[ ] sensor.tahoma.markdown
[ ] sensor.tcp.markdown
[ ] sensor.tellduslive.markdown
[ ] sensor.tellstick.markdown
[ ] sensor.tesla.markdown
[ ] sensor.thinkingcleaner.markdown
[ ] sensor.tibber.markdown
[ ] sensor.time_date.markdown
[ ] sensor.toon.markdown
[ ] sensor.tradfri.markdown
[ ] sensor.uber.markdown
[ ] sensor.upnp.markdown
[ ] sensor.ups.markdown
[ ] sensor.usps.markdown
[ ] sensor.velbus.markdown
[ ] sensor.vera.markdown
[ ] sensor.verisure.markdown
[ ] sensor.wink.markdown
[ ] sensor.wsdot.markdown
[ ] sensor.xiaomi_aqara.markdown
[ ] sensor.zha.markdown
[ ] sensor.zwave.markdown
[ ] shell_command.markdown
[ ] shopping_list.markdown
[ ] sonos.markdown
[x] switch.abode.markdown
[x] switch.amcrest.markdown
[x] switch.android_ip_webcam.markdown
[x] switch.broadlink.markdown
[x] switch.deconz.markdown
[x] switch.digitalloggers.markdown
[x] switch.edp_redy.markdown
[x] switch.eufy.markdown
[ ] switch.flux.markdown
[x] switch.fritzbox.markdown
[ ] switch.gc100.markdown
[x] switch.hive.markdown
[x] switch.homekit_controller.markdown
[x] switch.homematic.markdown
[x] switch.homematicip_cloud.markdown
[x] switch.insteon.markdown
[x] switch.isy994.markdown
[x] switch.konnected.markdown
[x] switch.litejet.markdown
[x] switch.lutron_caseta.markdown
[x] switch.markdown
[x] switch.mysensors.markdown
[x] switch.neato.markdown
[ ] switch.netio.markdown
[ ] switch.pulseaudio_loopback.markdown
[x] switch.qwikswitch.markdown
[x] switch.rachio.markdown
[x] switch.rainmachine.markdown
[ ] switch.rflink.markdown
[ ] switch.rpi_gpio.markdown
[ ] switch.rpi_pfio.markdown
[ ] switch.rpi_rf.markdown
[x] switch.smappee.markdown
[x] switch.spider.markdown
[x] switch.tahoma.markdown
[x] switch.tellduslive.markdown
[x] switch.tellstick.markdown
[x] switch.tesla.markdown
[x] switch.thinkingcleaner.markdown
[x] switch.toon.markdown
[x] switch.tradfri.markdown
[x] switch.tuya.markdown
[x] switch.velbus.markdown
[x] switch.vera.markdown
[x] switch.verisure.markdown
[x] switch.volvooncall.markdown
[x] switch.wemo.markdown
[x] switch.wink.markdown
[x] switch.xiaomi_aqara.markdown
[x] switch.zha.markdown
[x] switch.zwave.markdown
[x] telegram_bot.markdown
[x] timer.markdown
[x] tts.google.markdown
[x] tts.marytts.markdown
[x] updater.markdown
[x] usps.markdown
[x] vacuum.dyson.markdown
[x] vacuum.ecovacs.markdown
[x] vacuum.markdown
[x] vacuum.neato.markdown
[x] wake_on_lan.markdown
[x] weather.ecobee.markdown
[x] weather.markdown
[x] webhook.markdown
[x] websocket_api.markdown
[x] wemo.markdown
[x] zeroconf.markdown
[x] zwave.markdown

hmmbob commented 5 years ago

I tried finding some items I could help with, but it almost seems everything is done? Is there a way to find files that need help? Is there a list?

frenck commented 5 years ago

@hmmbob Configuration variables: is a good search string.

klaasnicolaas commented 5 years ago

44 files to go 😄

klaasnicolaas commented 5 years ago

After PR #7154 all the pages are done 😄

farmio commented 5 years ago

How should a configuration variable be described when it represents an enum (a string with only several acceptable values in my case)? Just type: string and all possible values listed in the description or type: string together with keys: key?

frenck commented 5 years ago

@farmio For YAML, it is still just a string...

frenck commented 5 years ago

The last PR, #7154 has been finished and merged.

Therefore, this issue can be closed! 🎉

Thank you all for your contributions. 👍 ❤️

A major shoutout to @klaasnicolaas who has done an impressive amount of PRs on this issue!🥇

home-assistant / home-assistant.io

Use the new style for configuration variables description #6385