From 2131bf7bcdd3f6fd22149327703d80eece4913a9 Mon Sep 17 00:00:00 2001
From: Raman Gupta <7243222+raman325@users.noreply.github.com>
Date: Mon, 29 May 2023 17:24:51 -0400
Subject: [PATCH] Add `datetime` entity developer docs (#1535)

---
 docs/core/entity/datetime.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 docs/core/entity/datetime.md

diff --git a/docs/core/entity/datetime.md b/docs/core/entity/datetime.md
new file mode 100644
index 00000000..b9066a58
--- /dev/null
+++ b/docs/core/entity/datetime.md
@@ -0,0 +1,36 @@
+---
+title: Date/Time Entity
+sidebar_label: Date/Time
+---
+
+A `datetime` is an entity that allows the user to input a timestamp to an integration. Derive entity platforms from [`homeassistant.components.datetime.DateTimeEntity`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/datetime/__init__.py)
+
+## Properties
+
+:::tip
+Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
+:::
+
+| Name | Type | Default | Description
+| ---- | ---- | ------- | -----------
+| native_value | datetime | **Required** | The value of the datetime. Must include timezone info.
+
+Other properties that are common to all entities such as `icon`, `name` etc are also applicable.
+
+## Methods
+
+### Set value
+
+Called when the user or an automation wants to update the value. The input datetime will always be in UTC.
+
+```python
+class MyDateTime(DateTimeEntity):
+    # Implement one of these methods.
+
+    def set_value(self, value: datetime) -> None:
+        """Update the current value."""
+
+    async def async_set_value(self, value: datetime) -> None:
+        """Update the current value."""
+
+```