Updated Configuration Variables sections #5929

tjorim · 2018-07-30T18:41:30Z

Description:

-Updates the Configuration Variables section of several components according to the docs: https://developers.home-assistant.io/docs/en/documentation_create_page.html

Fix some types to be in line with the rest
Some other small typo's

Checklist:

Branch: Fixes, changes and adjustments should be created against current. New documentation for platforms/components and features should go to next.
The documentation follow the standards.

Ref: #6385

Squashed commit of the following: commit a95d114 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Mon Jul 30 20:08:02 2018 +0200 Clean some things up commit db63a37 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Mon Jul 30 18:28:20 2018 +0200 Revert "The rest for this PR" This reverts commit bb1b2f9. commit df90512 Merge: deef4fd e4ed00d Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Mon Jul 30 17:05:27 2018 +0200 Merge remote-tracking branch 'upstream/current' into patch-1 commit deef4fd Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sun Jul 29 12:40:01 2018 +0200 Fix Liquid error commit 74369fb Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sun Jul 29 12:37:03 2018 +0200 Update Configuration Variables sections commit 6e50eaa Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sun Jul 29 11:52:51 2018 +0200 Fix empty keys commit 7e4852e Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sun Jul 29 11:41:46 2018 +0200 Update binary_sensor.netatmo.markdown commit e1d83df Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sun Jul 29 11:28:39 2018 +0200 More updated Configuration Variables sections commit 66cbe39 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 22:00:25 2018 +0200 Fix Liquid Exception sensor.speedtest commit bb1b2f9 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 21:54:34 2018 +0200 The rest for this PR - Update components with new Configuration Variables section to have YAML block syntax - Fix wrong capitalised booleans commit 5e67726 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 20:43:52 2018 +0200 Try multiline string in Cast Trying out a multiline string in a {% configuration %}-block. commit b8d34e9 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 20:41:39 2018 +0200 Lint fixes etc. All default True/False capital letters have been fixed. Tried to reduce lines to 80 characters or less where possible. commit 88228b2 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 16:32:46 2018 +0200 Update notify.webostv.markdown commit 7204c1d Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 16:15:18 2018 +0200 Fix capital letter commit 6e1b3db Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 16:14:05 2018 +0200 Update media_player.webostv.markdown commit 89ee235 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 16:08:59 2018 +0200 Update http.markdown commit 418f5cb Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 16:02:19 2018 +0200 Fix capital letter commit d5264c3 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 16:01:39 2018 +0200 Fix capital letter commit e4cd512 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 16:01:08 2018 +0200 Update sensor.iota.markdown commit c18b25f Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 16:01:01 2018 +0200 Fix capital letter commit 79a78f2 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:56:22 2018 +0200 Update Configuration Variables section commit 0db5228 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:54:47 2018 +0200 Update Configuration Variables section commit d5d26f1 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:54:14 2018 +0200 Update Configuration Variables section commit ab3f045 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:52:50 2018 +0200 Update Configuration Variables section commit 37b2d18 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:51:29 2018 +0200 Update Configuration Variables section commit 39b3ecd Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:50:53 2018 +0200 Update Configuration Variables section commit 823ea87 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:50:11 2018 +0200 Update Configuration Variables section commit 6560a2b Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:49:53 2018 +0200 Update Configuration Variables section commit cc97df2 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:47:23 2018 +0200 Update Configuration Variables section commit fdc881e Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:46:55 2018 +0200 Update Configuration Variables section commit 81e292c Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:46:16 2018 +0200 Update Configuration Variables section commit 05d3481 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:45:25 2018 +0200 Update Configuration Variables section commit ef34f8c Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:41:08 2018 +0200 Update Configuration Variables section commit 49f69a3 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:16:27 2018 +0200 Update Configuration Variables section commit 14732ee Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:14:58 2018 +0200 Update Configuration Variables section commit e0f8578 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:11:56 2018 +0200 Update media_player.samsungtv.markdown commit 8be3c95 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:10:45 2018 +0200 Update Configuration Variables section commit 53b6672 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:10:40 2018 +0200 Update media_player.webostv.markdown commit 421e903 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 15:03:33 2018 +0200 Update Configuration Variables section commit 7f142fd Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 14:59:54 2018 +0200 webOS brand fix + filename clarification commit 1f1051b Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 14:52:29 2018 +0200 Update sensor.yr.markdown commit 8be62f4 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 14:52:05 2018 +0200 Update Configuration Variables section commit 69c615b Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 14:50:57 2018 +0200 Update notify.webostv.markdown commit 4b1175e Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 14:50:30 2018 +0200 Update notify.html5.markdown commit 4ba06dd Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 14:49:59 2018 +0200 Update image_processing.openalpr_local.markdown commit ec919d5 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 14:49:18 2018 +0200 Update image_processing.microsoft_face_detect.markdown commit da657b5 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 14:42:46 2018 +0200 Update Configuration Variables section commit 3b066ba Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 14:40:33 2018 +0200 Update Configuration Variables section commit 360c542 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 14:38:54 2018 +0200 Update Configuration Variables section commit 7965ff8 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 13:51:12 2018 +0200 Update Configuration Variables section commit 48d20dd Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 13:48:33 2018 +0200 Update Configuration Variables section commit 4c6efe7 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 13:40:33 2018 +0200 Update Configuration Variables section commit 8c45d83 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 13:35:19 2018 +0200 Update Configuration Variables section commit bbfa64a Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 13:33:14 2018 +0200 Newline commit f0577bb Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 13:32:54 2018 +0200 Fix typo commit 65f73ce Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 13:19:23 2018 +0200 Update notify.webostv.markdown commit 1a11c97 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 13:18:44 2018 +0200 Update notify.html5.markdown commit 4653233 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 13:18:04 2018 +0200 Update image_processing.openalpr_local.markdown commit ce9ca34 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Sat Jul 28 13:15:05 2018 +0200 Update Configuration Variables section commit 6ae8a40 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Thu Jul 26 22:58:55 2018 +0200 Update Configuration Variables section commit c4bed22 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Thu Jul 26 22:56:35 2018 +0200 Update Configuration Variables section commit 9fe09af Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 23:46:23 2018 +0200 Update Configuration Variables section commit 8efc72f Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 23:44:08 2018 +0200 Update image_processing.openalpr_cloud.markdown commit 52046e5 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 23:43:52 2018 +0200 Update Configuration Variables section commit c7a9296 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 23:27:08 2018 +0200 Update image_processing.microsoft_face_detect.markdown commit 3b37dc0 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 23:20:26 2018 +0200 Update Configuration Variables section commit 870cd41 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 23:18:38 2018 +0200 Update image_processing.microsoft_face_identify.markdown commit 0f76212 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 23:17:09 2018 +0200 Update Configuration Variables section commit 73513b9 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 23:13:26 2018 +0200 Update image_processing.microsoft_face_detect.markdown commit c171a08 Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 23:01:06 2018 +0200 Update image_processing.microsoft_face_detect.markdown commit 294a37f Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 21:46:14 2018 +0200 Update image_processing.microsoft_face_detect.markdown commit 9f4c3fa Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 21:21:17 2018 +0200 Update image_processing.microsoft_face_detect.markdown commit 11579aa Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 21:13:30 2018 +0200 Update camera.mjpeg.markdown commit e93f5db Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 19:34:36 2018 +0200 Update Configuration Variables section commit 383b9ac Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 17:49:38 2018 +0200 Remove leftover line commit 7e2e72f Author: Jorim Tielemans <tielemans.jorim@gmail.com> Date: Wed Jul 25 17:46:55 2018 +0200 Update Configuration Variables section

frenck · 2018-07-31T09:45:14Z

@tjorim Could you fix the merge conflict? 👍

…-patch-1

fabaff · 2018-07-31T16:54:22Z

My problem with this PR is that it contains a lot of new line breaks. This would make sense if we would have a limit of the line length but we don't. We want people to use the online GitHub editor to keep the barrier very low for new contributors and this editor has no visual helper for the line length.

Beside that nice work.

frenck · 2018-07-31T17:10:31Z

@fabaff Interesting comment, nevertheless, the larger part of Markdown specs/guides/linters do not agree (I know this since I wrote pretty extensive style guides on Markdown in the past).

tjorim · 2018-07-31T17:38:52Z

@fabaff At first I didn't have any line breaks, I even removed it in some places because I had a feeling that in most documentation there were none either.
It was after a preliminary review by @dale3h (https://github.com/home-assistant/home-assistant.io/pull/5887/files/88228b293ddef2630653c5636d2b75606106742b) on the previous PR I introduced it.

Please reduce all lines to 80 characters or less where possible. To reduce lines with URLs, it is preferred to use reference links in the entire document.

After some talking on Discord I tried if this could be done in {% configuration %} blocks as well, since some people prefer it restricted to <=80 characters per line.

Nevertheless I appreciate the feedback! Maybe things like that could/should be clarified in the Documentation standards documentation as well?
Furthermore we could perhaps consider implementing a linter like Markdownlint? Just like Hound in the Home Assitant repository itself. (Hound supports it but only as alpha since 2016, houndci/hound#1072)

Was also wondering why I never had to sign the CLA, it mentions that to sign the CLA you must submit a PR. I was expecting this to happen like in the Home Assistant repo, but never got this request from a bot or so.

fabaff · 2018-08-01T08:51:32Z

My point of view is that with markdown we are talking about a formatting syntax and not code. A lot of contributions are done with the online editor and as long as this editor doesn't support requirements we may set the frustration of contributors will increase.

the larger part of Markdown specs/guides/linters do not agree

I know because they handle it as code, are referring to it is as code or were written by developers and not writers. As far as I remember doesn't make the original Markdown write-up a statement about the line length to use.

To reduce lines with URLs, it is preferred to use reference links in the entire document.

For me this is something that make writing content harder for newbies and only add value if the link is used
more than once or the content is generated.

tjorim · 2018-08-01T09:25:21Z

@fabaff Agree with you on the last one, so I didn't do that.
It would regress the readability of the 'code' in my opinion.

tjorim · 2018-08-14T19:54:11Z

Resolved merge conflicts again.

tjorim · 2018-09-03T19:59:39Z

It feels like I can stay busy with this 😆

frenck · 2018-09-30T07:27:25Z

frenck · 2018-09-30T08:01:26Z

@tjorim On a lot of occasions you encapsulate the description with double quotes when that is not needed.

As a result of this, the encapsulation is visible in the frontend. See for example the alert component, variables: repeat, skip_first.

https://deploy-preview-5929--home-assistant-docs.netlify.com/components/alert/

tjorim · 2018-09-30T10:45:57Z

Alright, fixing them now. Apparently encapsulation is never needed when using >.

Edit: should all be fixed, awaiting the deploy.

Double quotes were visible in the frontend.

frenck · 2018-09-30T15:57:31Z

source/_components/binary_sensor.workday.markdown

+    [holidays](https://pypi.python.org/pypi/holidays/0.9.4) notation.
+  required: false
+  type: string
+  default: None


So no default? Remove it?

That might be better indeed, since the original documentation mentioned it I thought it was documentation worthy.

frenck · 2018-09-30T16:48:03Z

source/_components/http.markdown

  required: false
  type: string
-  default: The local IP address
+  default: "*the local IP address*"


Defaults are already rendered as italic, adding some extra is not going to change a thing.

frenck · 2018-09-30T16:57:51Z

source/_components/joaoapps_join.markdown

+device_ids:
+  description: Comma separated list of device ids.
+  required: false
+  type: list


Comma-separated list: This is a string.

https://github.com/home-assistant/home-assistant/blob/1b7bfec2477e98be8b1428085e5d40d1e9943c3e/homeassistant/components/joaoapps_join.py#L27

frenck · 2018-09-30T16:58:14Z

source/_components/joaoapps_join.markdown

+device_names:
+  description: Comma separated list of device names.
+  required: false
+  type: list


Comma-separated list: This is a string.

https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/joaoapps_join.py#L28

frenck · 2018-09-30T18:38:02Z

This is definitely the largest docs PR I've ever reviewed AND approved.

✅ Approved.

Absolutely wonderful job @tjorim you are a champ!

(But pretty please do smaller PR's next time 🤣 )

tjorim · 2018-09-30T18:40:45Z

Will do, thanks for fixing the mistakes that were left.

jeepers58 · 2018-10-02T03:12:14Z

Hi,
How would I go about checking the updates I made to a markdown file? I would like to preview my work before submitting ?

frenck · 2018-10-02T08:45:24Z

@jeepers58 Please don't start dicussions/support questions on random PRs.
We have a community forum, a discord and GitHub issues for these kinds of things.

Regarding your answer, please check the developers' documentation on https://developers.home-assistant.io

ghost added the to-do label Jul 30, 2018

tjorim mentioned this pull request Jul 30, 2018

Update Configuration Variables section #5887

Closed

2 tasks

frenck added spelling ready-for-review This PR needs to be reviewed current This PR goes into the current branch and removed to-do labels Jul 31, 2018

Merge remote-tracking branch 'upstream/current' into tjorim-conf-vars…

e1bfc9d

…-patch-1

tjorim added 2 commits August 8, 2018 23:09

Merge branch 'current' into tjorim-conf-vars-patch-1

9564e95

Merge branch 'current' into tjorim-conf-vars-patch-1

22545a0

frenck self-assigned this Aug 17, 2018

tjorim added 4 commits August 18, 2018 10:29

Merge branch 'current' into tjorim-conf-vars-patch-1

8180e54

Merge branch 'current' into tjorim-conf-vars-patch-1

424d3ce

Merge branch 'current' into tjorim-conf-vars-patch-1

c0e9f8b

Merge branch 'current' into tjorim-conf-vars-patch-1

8a2287d

Merge branch 'current' into tjorim-conf-vars-patch-1

b9846f9

frenck removed their assignment Sep 10, 2018

tjorim added 2 commits September 10, 2018 17:16

Merge branch 'current' into tjorim-conf-vars-patch-1

ba328f0

Merge branch 'current' into tjorim-conf-vars-patch-1

4f843d2

frenck self-assigned this Sep 30, 2018

Merge branch 'current' into tjorim-conf-vars-patch-1

fa01535

Remove encapsulation

344b4f0

Double quotes were visible in the frontend.

frenck reviewed Sep 30, 2018

View reviewed changes

Remove empty default value

a609dfc

frenck reviewed Sep 30, 2018

View reviewed changes

frenck added 2 commits September 30, 2018 20:13

🚑 Correcting types

80ae532

✏️ Removes double italic

4de353f

frenck approved these changes Sep 30, 2018

View reviewed changes

frenck merged commit 77eef89 into home-assistant:current Sep 30, 2018

ghost removed the ready-for-review This PR needs to be reviewed label Sep 30, 2018

tjorim deleted the tjorim-conf-vars-patch-1 branch September 30, 2018 18:41

home-assistant locked and limited conversation to collaborators Oct 2, 2018

Uh oh!

Updated Configuration Variables sections #5929

Updated Configuration Variables sections #5929

Uh oh!

Conversation

tjorim commented Jul 30, 2018 • edited by frenck Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist:

Uh oh!

frenck commented Jul 31, 2018

Uh oh!

fabaff commented Jul 31, 2018

Uh oh!

frenck commented Jul 31, 2018

Uh oh!

tjorim commented Jul 31, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fabaff commented Aug 1, 2018

Uh oh!

tjorim commented Aug 1, 2018

Uh oh!

tjorim commented Aug 14, 2018

Uh oh!

tjorim commented Sep 3, 2018

Uh oh!

frenck commented Sep 30, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

frenck commented Sep 30, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tjorim commented Sep 30, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

frenck Sep 30, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tjorim Sep 30, 2018

Choose a reason for hiding this comment

Uh oh!

frenck Sep 30, 2018

Choose a reason for hiding this comment

Uh oh!

frenck Sep 30, 2018

Choose a reason for hiding this comment

Uh oh!

frenck Sep 30, 2018

Choose a reason for hiding this comment

Uh oh!

frenck commented Sep 30, 2018

Uh oh!

tjorim commented Sep 30, 2018

Uh oh!

jeepers58 commented Oct 2, 2018

Uh oh!

frenck commented Oct 2, 2018

Uh oh!

Uh oh!

tjorim commented Jul 30, 2018 •

edited by frenck

Loading

tjorim commented Jul 31, 2018 •

edited

Loading

frenck commented Sep 30, 2018 •

edited

Loading

frenck commented Sep 30, 2018 •

edited

Loading

tjorim commented Sep 30, 2018 •

edited

Loading

frenck Sep 30, 2018 •

edited

Loading