(WIP) Restructure usage documentation

[michikrug]

This PR reworks the current usage documentation to be more structured and helpful.
It adds sections for every device supported with their options and example usage.

[Legion2]

Will the documentation also be available in the new main UI of openHAB 3, so we can configure google assistant mainly from the main UI?

[michikrug]

Will the documentation also be available in the new main UI of openHAB 3, so we can configure google assistant mainly from the main UI?

Do you refer to what is defined in /~https://github.com/openhab/openhab-webui/blob/main/bundles/org.openhab.ui/web/src/assets/definitions/metadata/ga.js which is used to create the "Edit Item Metadata" UI?

[Legion2]

@michikrug Yes, it is missing all the new items and settings and I only use the main UI, so I can not configure them. (Workaround: I have to edit the yaml config in the UI, which is error-prone and time consuming)

[michikrug]

Maybe we can loop in @eikowagenknecht who was already contributing to those docs in the past and try to find a nice way to keep those things in sync...

[michikrug]

Would it make sense that the devices expose this information directly so that it can be gathered and used to "generate" the information for openHAB?

E.g.: /~https://github.com/michikrug/openhab-google-assistant/blob/23d7e59b3aca9b1f6bac1efb1c189e2f1bfe9d5a/functions/devices/tv.js#L4

[eikowagenknecht]

Maybe we can loop in @eikowagenknecht who was already contributing to those docs in the past and try to find a nice way to keep those things in sync...

I can sync this up again, manually though. An automatic mechanism would be nice, but I have no idea how to build that.

Is the current state of your new binding / documentation the final one or should I wait some more?

[michikrug]

Maybe we can loop in @eikowagenknecht who was already contributing to those docs in the past and try to find a nice way to keep those things in sync...

I can sync this up again, manually though. An automatic mechanism would be nice, but I have no idea how to build that.

Is the current state of your new binding / documentation the final one or should I wait some more?

1. If we would go for the proposal as stated in my last comment, we could at least provide a script that kinda generates the metadata for the openHAB UI, that would probably still need to be PR'd manually.

2. For now I would keep it pretty stable and only add new features. So you could take the contents of this PR for updating the metadata.

[eikowagenknecht]

A few remarks / questions from my side:

• Is there a reason that the "Sensor" device (sensor.js) is not in the documentations at all? I'm wondering if I should make UI entries available for that one.

• I see that thermostatTemperatureSetpointHigh and thermostatTemperatureSetpointLow have been removed from the docs. I think they should either be also removed from the code (thermostat.js) or reintroduced in the docs. The current state is confusing.

• In the docs for TV it says "availableApplications" is supported. I can not see that anywhere in the code (tv.js). Neither can I see the mentioned AppSelector Trait or the tvApplication item. Is this still to be implemented (then it should not yet be in the docs) or am I missing something?

• The "lang" parameter is mentioned twice for Fan / Hood / AirPurifier. Also: Are you sure "en|de" is valid? The google docs just mention "Language code (ISO 639-1). See supported languages." but not that there can be multiple aligned with "|".

[michikrug]

@eikowagenknecht Thanks for your review. This is what I rely on :)

1. Sensor is probably just missed. I will add a rough theoretical description, although I never got it working neither with voice or UI.

2. Probably also just missed, will be added.

3. This is implemented in Add AppSelector trait for TV #201 and I did not want to touch the old docu there.

4. No, "en|de" is not valid but meant to be use either this or that. Thus, I will need to change the syntax in the docu to be self-explanatory.

[eikowagenknecht]

Thanks for the clarification @michikrug

I created a PR to sync the UI up to the current state - openhab/openhab-webui#1017

[michikrug]

@eikowagenknecht I have adjusted the documentation with respect to your comments

[eikowagenknecht]

Great. Just one thing: You missed an equals sign with the sensor example:

states"good=10,moderate=50,poor=90"

[michikrug]

Thanks for the clarification @michikrug

I created a PR to sync the UI up to the current state - openhab/openhab-webui#1017

Great @eikowagenknecht!

I only would advice to change the TFA attributes to the more Google aligned ackNeeded and pinNeeded that I also introduced with the refactoring. The old ones are kept for now to not expose people's devices with the deployment.

But as this is not live yet. Let's wait for after the release.

[eikowagenknecht]

Done, allthough I had to create a new PR for this because @ghys is so fast with the merging :-)