differentiate between how a component is defined, and how it is used

[donburch888]

Describe the improvement

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.*”

Anything else?

No response

[donburch888]

Taking Binary Sensor as an example - 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. The Table of Contents becomes:

Binary Sensor Component
    Base Binary Sensor Configuration
    Binary Sensor Filters
        invert
        delayed_on
        delayed_off
        delayed_on_off
        autorepeat
        lambda
        settle
        timeout
    Binary Sensor Automation
        on_press
        on_release
        on_state
        on_state_change
        on_click
        on_double_click
        on_multi_click
    Referencing Binary Sensor
        binary_sensor.invalidate_state Action
        binary_sensor.is_on / binary_sensor.is_off Condition
        lambda calls
    See Also