Add documentation for new Valve integration (#29572)

* Add documentation for new Valve integration

* Update target version

* Set version to 2024.1.0

* Tiny tweaks

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* Apply suggestions from code review

* Tweak

* Update source/_integrations/valve.markdown

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>

* Update source/_integrations/valve.markdown

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>

* Clarify what 0 and 100 mean in the position field

* tiny tweak

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

CODEOWNERS

@@ -804,6 +804,7 @@ source/_integrations/utility_meter.markdown @dgomes
 source/_integrations/v2c.markdown @dgomes
 source/_integrations/vacuum.markdown @home-assistant/core
 source/_integrations/vallox.markdown @andre-richter @slovdahl @viiru-
+source/_integrations/valve.markdown @home-assistant/core
 source/_integrations/velbus.markdown @Cereal2nd @brefra
 source/_integrations/velux.markdown @Julius2342
 source/_integrations/venstar.markdown @garbled1 @jhollowe

source/_data/glossary.yml

@@ -387,6 +387,14 @@
   definition: >-
     TTS (text-to-speech) allows Home Assistant to talk to you.
   link: /integrations/tts/
+
+
+- term: Valve
+  definition: >-
+    Valves are devices to control the flow of liquids and gases. All valves in Home Assistant can be opened
+    and closed. Some valves can also be set to a specific position.
+  link: /integrations/valve
+
 - term: Variables
   definition: >-
     Variables are used to store values in memory that can be processed

source/_integrations/valve.markdown

@@ -0,0 +1,72 @@
+---
+title: Valve
+description: Instructions on how to integrate valves into Home Assistant.
+ha_category:
+  - Valve
+ha_release: 2024.1.0
+ha_quality_scale: internal
+ha_codeowners:
+  - '@home-assistant/core'
+ha_domain: valve
+ha_integration_type: entity
+---
+
+The valve entity in Home Assistant provides an interface to control valves such as water, gas, or air valves.
+
+{% include integrations/building_block_integration.md %}
+
+## Device class
+
+You can change the device class of the valve in the [customize section](/docs/configuration/customizing-devices/). Valves support the following device classes:
+
+- **None**: Generic valve. This is the default and doesn't need to be set.
+- **water**: Valve that controls the flow of water through a system.
+- **gas**: Valve that controls the flow of gas through a system.
+
+## Services
+
+### Valve control services
+
+All valves respond to `valve.open`, `valve.close`, and `valve.toggle`.
+Valves that allow setting a specific position may also be controlled with `valve.set_position` and `valve.stop`.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String or list of strings that point at `entity_id`'s of valves. Use `entity_id: all` to target all.
+
+#### Automation example
+
+```yaml
+automation:
+  trigger:
+    platform: time
+    at: "07:15:00"
+  action:
+    - service: valve.close
+      target:
+        entity_id: valve.demo
+```
+
+### Service `valve.set_position`
+
+Set the position of one or multiple valves if they support setting a specific position.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String or list of strings that point at `entity_id`'s of valves. Use `entity_id: all` to target all.
+| `position` | no | Integer between 0 (fully closed) and 100 (fully open).
+
+#### Automation example
+
+```yaml
+automation:
+  trigger:
+    platform: time
+    at: "07:15:00"
+  action:
+    - service: valve.set_position
+      target:
+        entity_id: valve.demo
+      data:
+        position: 50
+```