Each ESPHome component documentation page currently starts with a brief overview, then the Base Component Configuration which lists all the configuration variables, and then all other information is presented in one list generally under one “Automation” heading. I believe we should differentiate between how a component is defined, and how it is used.
While these are all automations, some are for use in the component’s configuration (eg on_value:) and triggered when the value of the component is changed. These should be listed under the Base Configuration heading.
Other automations are used elsewhere to get, test (eg sensor.in_range), or change the value of a component. I believe that a separate level 1 section for “Referencing Component” would help to clarify where an automation should be used.
It will also help reduce confusion from contradictory statements appearing together, such as in the Sensor Component page where
“You can access the most recent state of the sensor in lambdas using id(sensor_id).state and the most recent raw state using id(sensor_id).raw_state.”
is immediately followed by
“* … In Lambdas you can get the value from the trigger with x.*”
You will need to point to specific examples, e.g. the https://new.esphome.io/components/binary_sensor/ documentation page does list the automation triggers in the base configuration section, but discusses actions and conditions later. If there are other components where that pattern isn’t followed, by all means propose improvements, but without specifics there’s nowhere to start.
Binary Sensor is a pretty good example - but even there I would suggest moving the binary_sensor.invalidate_state Action down to below on_multi_click. This will group those entries which reference a binary sensor separately to those which define a binary_sensor. Note that there are two “lambda” sections, depending on how they are used.
So the best way to help out with this will be to raise PRs on the docs site. I know you raised a feature request, but the reality is that feature requests only get implemented when someone who has a need for that feature spends the time on it.
Clearly you’re motivated to improve the docs, and it’s not too hard to do. I’d suggest wait until after the upcoming release (next week) when the docs will be converted to Markdown format, which is more familiar to many people. Then get stuck in, ask for help if needed to get started, but after you’ve completed the first PR it will be easy.
I see the documentation has changed to the new format, and I’m happy to start making changes. But I also anticipate that any changes will ultimately be met with “rejected because it doesn’t match our documentation style” - I have watched that before - and so this thread was to try to get some feeling for whether users and HA authorities would object to this change.
The ESPHome documentation guidelines give no guidance on the organisation/layout, and I suspect that adding to the documentation guidelines is the appropriate place to start. I acknowledge that no layout will suit every case, but suggest the following structure for component documentation:
Base [component] Configuration
[component] Filters (if any)
[component] Actions
Referencing [component]
See Also
… where [component] Filters and [component] Actions include only those which should appear in the component’s configuration section of yaml code.
Referencing [component] should include any Conditions, Actions, lambdas (or whatever) that might refer to the [component] but be used anywhere else in yaml code. Eg in some other component’s yaml code
on_value:
if:
condition:
# Same syntax for is_off
binary_sensor.is_on: my_binary_sensor
The other thing is a minor point, but which I have seen derail perfectly good suggestions by generating a lot of argument … what to label the various sections ? In my example above I used “Reference Actions” because they refer to entities from different entities … but I expect people will interpret that phrase differently.