Document rounded and with_unit arguments to states template function (#26175)

source/_docs/configuration/templating.markdown

@@ -72,7 +72,9 @@ Not supported in [limited templates](#limited-templates).
 - Iterating `states` will yield each state sorted alphabetically by entity ID.
 - Iterating `states.domain` will yield each state of that domain sorted alphabetically by entity ID.
 - `states.sensor.temperature` returns the state object for `sensor.temperature` (avoid when possible, see note below).
-- `states('device_tracker.paulus')` will return the state string (not the object) of the given entity, `unknown` if it doesn't exist, `unavailable` if the object exists but is not yet available.
+- `states` can also be used as a function, `states(entity_id, rounded=False, with_unit=False)`, which returns the state string (not the state object) of the given entity, `unknown` if it doesn't exist, and `unavailable` if the object exists but is not available.
+  - The optional arguments `rounded` and `with_unit` control the formatting of sensor state strings, please see the [examples](#formatting-sensor-states) below.
+- `states.sensor.temperature.state_with_unit` formats the state string in the same was is if calling `states('sensor.temperature', rounded=True, with_unit=True)`.
 - `is_state` compares an entity's state with a specified state or list of states and returns `True` or `False`. `is_state('device_tracker.paulus', 'home')` will test if the given entity is the specified state. `is_state('device_tracker.paulus', ['home', 'work'])` will test if the given entity is any of the states in the list.
 - `state_attr('device_tracker.paulus', 'battery')` will return the value of the attribute or None if it doesn't exist.
 - `is_state_attr('device_tracker.paulus', 'battery', 40)` will test if the given entity attribute is the specified state (in this case, a numeric value). Note that the attribute can be `None` and you want to check if it is `None`, you need to use `state_attr('sensor.my_sensor', 'attr') is none` or `state_attr('sensor.my_sensor', 'attr') == None` (note the difference in the capitalization of none in both versions).
@@ -83,8 +85,6 @@ Not supported in [limited templates](#limited-templates).
 
 </div>
 
-Besides the normal [state object methods and properties](/topics/state_object/), `states.sensor.temperature.state_with_unit` will print the state of the entity and, if available, the unit.
-
 #### States examples
 
 The next two statements result in the same value if the state exists. The second one will result in an error if the state does not exist.
@@ -159,6 +159,52 @@ Other state examples:
 
 {% endraw %}
 
+#### Formatting sensor states
+
+The examples below show the output of a temperature sensor with state `20.001`, unit `°C` and user configured presentation rounding set to 1 decimal.
+
+This results in the number `20.001`:
+{% raw %}
+```text
+{{ states('sensor.temperature') }}
+```
+{% endraw %}
+
+This results in the string `"20.0 °C"`:
+{% raw %}
+```text
+{{ states('sensor.temperature', with_unit=True) }}
+```
+{% endraw %}
+
+This results in the string `"20.001 °C"`:
+{% raw %}
+```text
+{{ states('sensor.temperature', with_unit=True, rounded=False) }}
+```
+{% endraw %}
+
+This results in the number `20.0`:
+{% raw %}
+```text
+{{ states('sensor.temperature', rounded=True) }}
+```
+{% endraw %}
+
+This results in the number `20.001`:
+{% raw %}
+```text
+{{ states.sensor.temperature.state }}
+```
+{% endraw %}
+
+This results in the string `"20.0 °C"`:
+{% raw %}
+```text
+{{ states.sensor.temperature.state_with_unit }}
+```
+{% endraw %}
+
 ### Attributes
 
 Not supported in [limited templates](#limited-templates).