From 150d149d6008ce3e209e4e0796964fbfe62f536e Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Fri, 23 Dec 2022 11:57:01 +1300
Subject: [PATCH] Restructure time docs into its own folder and split (#2566)

---
 changelog/v1.10.0.rst                     |   2 +-
 components/climate/bedjet.rst             |   2 +-
 components/display/pvvx_mithermometer.rst |   2 +-
 components/gps.rst                        |   8 +-
 components/index.rst                      |   2 +
 components/time/ds1307.rst                |  99 +++++++++++++
 components/time/gps.rst                   |  23 ++++
 components/time/homeassistant.rst         |  24 ++++
 components/{time.rst => time/index.rst}   | 160 ++--------------------
 components/time/sntp.rst                  |  34 +++++
 components/tuya.rst                       |   2 +-
 index.rst                                 |  12 +-
 12 files changed, 210 insertions(+), 160 deletions(-)
 create mode 100644 components/time/ds1307.rst
 create mode 100644 components/time/gps.rst
 create mode 100644 components/time/homeassistant.rst
 rename components/{time.rst => time/index.rst} (79%)
 create mode 100644 components/time/sntp.rst

diff --git a/changelog/v1.10.0.rst b/changelog/v1.10.0.rst
index b2cf21eec..f82f675bb 100644
--- a/changelog/v1.10.0.rst
+++ b/changelog/v1.10.0.rst
@@ -142,7 +142,7 @@ Other notable changes:
   ``esphomeyaml.includes`` and ``esphomeyaml.platformio_options`` (:doc:`/components/esphome`)
 - Saved a lot of flash space on ESP8266 boards. Previously, platformio would allocate about 1/4 of flash for SPIFFS,
   but esphomelib doesn't use that so now you have that as extra storage. Thanks `@brandond <http://github.com/brandond>`
-- You can now use Home Assistant to get time in ESPHome, so no more need for SNTP. See :ref:`time`.
+- You can now use Home Assistant to get time in ESPHome, so no more need for SNTP. See :doc:`/components/time/index`.
 
 Release 1.10.1 - January 13
 ---------------------------
diff --git a/components/climate/bedjet.rst b/components/climate/bedjet.rst
index 7e4c3ee57..b092eaf61 100644
--- a/components/climate/bedjet.rst
+++ b/components/climate/bedjet.rst
@@ -43,7 +43,7 @@ Configuration variables:
 
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 - **ble_client_id** (**Required**, :ref:`config-id`): The ID of the BLE Client.
-- **time_id** (*Optional*, :ref:`config-id`): The ID of a :ref:`Time Component <time>` which
+- **time_id** (*Optional*, :ref:`config-id`): The ID of a :doc:`/components/time/index` which
   can be used to set the time on the BedJet device.
 - **update_interval** (*Optional*, :ref:`config-time`): The interval to dispatch status
   changes to child components. Defaults to ``5s``. Each child component can decide whether to
diff --git a/components/display/pvvx_mithermometer.rst b/components/display/pvvx_mithermometer.rst
index 7aa69b633..799b25333 100644
--- a/components/display/pvvx_mithermometer.rst
+++ b/components/display/pvvx_mithermometer.rst
@@ -48,7 +48,7 @@ Configuration variables:
 ------------------------
 
 - **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client.
-- **time_id** (*Optional*, :ref:`config-id`): ID of a :doc:`/components/time` component. If set, the time will be synchronized with every connection.
+- **time_id** (*Optional*, :ref:`config-id`): ID of a :doc:`/components/time/index`. If set, the time will be synchronized with every connection.
 - **disconnect_delay** (*Optional*, :ref:`config-time`): The amount of time the BLE connection is maintained before being disconnected again. Defaults to ``5s``.
 - **update_interval** (*Optional*, :ref:`config-time`): The interval to transmit the display data. Defaults to ``60s``.
 - **validity_period** (*Optional*, :ref:`config-time`): The time periode for which the pvvx device should display the information. Defaults to ``5min``.
diff --git a/components/gps.rst b/components/gps.rst
index d219b7d34..b674cf1ff 100644
--- a/components/gps.rst
+++ b/components/gps.rst
@@ -40,13 +40,13 @@ in your configuration - only the RX pin should be necessary.
       - platform: gps
 
 The component is split up in platforms, by defining the GPS module
-(as seen above). 
+(as seen above).
 
-In addition to retrieving GPS position data, the module can also be used as a 
-time platform to get the current date and time via the very accurate GPS clocks 
+In addition to retrieving GPS position data, the module can also be used as a
+time platform to get the current date and time via the very accurate GPS clocks
 without a network connection.
 
-See :doc:`time` for config options for the GPS time source.
+See :doc:`time/gps` for config options for the GPS time source.
 
 Configuration variables:
 ------------------------
diff --git a/components/index.rst b/components/index.rst
index a873c9e66..1b2dd79a2 100644
--- a/components/index.rst
+++ b/components/index.rst
@@ -2,6 +2,7 @@ Components
 ==========
 
 .. toctree::
+    :maxdepth: 3
     :glob:
 
     binary_sensor/index
@@ -22,4 +23,5 @@ Components
     lock/index
     display_menu/index
     media_player/index
+    time/index
     *
diff --git a/components/time/ds1307.rst b/components/time/ds1307.rst
new file mode 100644
index 000000000..5676b252b
--- /dev/null
+++ b/components/time/ds1307.rst
@@ -0,0 +1,99 @@
+DS1307 Time Source
+==================
+
+You first need to set up the :doc:`I2C </components/i2c>` component.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    time:
+      - platform: ds1307
+        id: ds1307_time
+
+Configuration variables
+-----------------------
+
+- **address** (*Optional*, int): Manually specify the I²C address of the RTC. Defaults to ``0x68``.
+- All other options from :ref:`base_time_config`.
+
+
+.. _ds1307-write_time_action:
+
+``ds1307.write_time`` Action
+----------------------------
+
+This :ref:`Action <config-action>` triggers a synchronization of the current system time to the RTC hardware.
+
+.. note::
+
+    The DS1307 component will *not* write the RTC clock if not triggered *explicitly* by this action.
+
+.. code-block:: yaml
+
+    on_...:
+      - ds1307.write_time
+
+      # in case you need to specify the DS1307 id
+      - ds1307.write_time:
+          id: ds1307_time
+
+
+.. _ds1307-read_time_action:
+
+``ds1307.read_time`` Action
+---------------------------
+
+This :ref:`Action <config-action>` triggers a synchronization of the current system time from the RTC hardware.
+
+.. note::
+
+    The DS1307 component will automatically read the RTC clock every 15 minutes by default and synchronize the
+    system clock when a valid timestamp was read from the RTC. (The ``update_interval`` can be changed.)
+    This action can be used to trigger *additional* synchronizations.
+
+.. code-block:: yaml
+
+    on_...:
+      - ds1307.read_time
+
+      # in case you need to specify the DS1307 id
+      - ds1307.read_time:
+          id: ds1307_time
+
+
+.. _ds1307-config_example:
+
+Full Configuration Example
+--------------------------
+
+In a typical setup, you will have at least one additional time source to synchronize the RTC with. Such an
+external time source might not always be available e.g. due to a limited network connection.
+In order to have a valid, reliable system time, the system should read the RTC once at start and then try to
+synchronize with an external reliable time source.
+When a synchronization to another time source was successful, the RTC can be resynchronized.
+
+.. code-block:: yaml
+
+    esphome:
+      on_boot:
+        then:
+          # read the RTC time once when the system boots
+          ds1307.read_time:
+
+    time:
+      - platform: ds1307
+        # repeated synchronization is not necessary unless the external RTC
+        # is much more accurate than the internal clock
+        update_interval: never
+      - platform: homeassistant
+        # instead try to synchronize via network repeatedly ...
+        on_time_sync:
+          then:
+            # ... and update the RTC when the synchronization was successful
+            ds1307.write_time:
+
+
+See Also
+--------
+
+- :ghedit:`Edit`
diff --git a/components/time/gps.rst b/components/time/gps.rst
new file mode 100644
index 000000000..a2f3f2c3a
--- /dev/null
+++ b/components/time/gps.rst
@@ -0,0 +1,23 @@
+GPS Time Source
+===============
+
+You first need to set up the :doc:`GPS </components/gps>` component.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    time:
+      - platform: gps
+        id: gps_time
+
+
+Configuration variables
+-----------------------
+
+- All options from :ref:`base_time_config`.
+
+
+See Also
+--------
+
+- :ghedit:`Edit`
diff --git a/components/time/homeassistant.rst b/components/time/homeassistant.rst
new file mode 100644
index 000000000..50cece7ec
--- /dev/null
+++ b/components/time/homeassistant.rst
@@ -0,0 +1,24 @@
+Home Assistant Time Source
+==========================
+
+The preferred way to get time in ESPHome is using Home Assistant.
+With the ``homeassistant`` time platform, the :doc:`native API </components/api>` connection
+to Home Assistant will be used to periodically synchronize the current time.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    time:
+      - platform: homeassistant
+        id: homeassistant_time
+
+Configuration variables
+-----------------------
+
+- All options from :ref:`base_time_config`.
+
+
+See Also
+--------
+
+- :ghedit:`Edit`
diff --git a/components/time.rst b/components/time/index.rst
similarity index 79%
rename from components/time.rst
rename to components/time/index.rst
index 7a4ecad44..1ea6b694d 100644
--- a/components/time.rst
+++ b/components/time/index.rst
@@ -1,7 +1,5 @@
-.. _time:
-
-Time
-====
+Time Component
+==============
 
 .. seo::
     :description: Instructions for setting up real time clock sources in ESPHome like network based time.
@@ -57,7 +55,7 @@ This powerful automation can be used to run automations at specific intervals at
 specific times of day. The syntax is a subset of the `crontab <https://crontab.guru/>`__ syntax.
 
 There are two ways to specify time intervals: Either with using the ``seconds:``, ``minutes:``, ...
-keys as seen below or using a cron alike expression like ``* /5 * * * *``. 
+keys as seen below or using a cron alike expression like ``* /5 * * * *``.
 
 Be aware normal cron implementations does not know about seconds like this esphome implementation, therefore you got 6 fields (seconds,minutes,hours,dayofmonth,month,dayofweek).
 
@@ -199,156 +197,10 @@ to an external hardware real time clock chip.
     the system time. Some (such as SNTP) could even trigger when another real time component is responsible for the
     change in time.
 
-Home Assistant Time Source
---------------------------
 
-The preferred way to get time in ESPHome is using Home Assistant.
-With the ``homeassistant`` time platform, the :doc:`native API </components/api>` connection
-to Home Assistant will be used to periodically synchronize the current time.
 
-.. code-block:: yaml
 
-    # Example configuration entry
-    time:
-      - platform: homeassistant
-        id: homeassistant_time
 
-Configuration variables:
-
-- All other from :ref:`base_time_config`.
-
-SNTP Time Source
-----------------
-
-.. code-block:: yaml
-
-    # Example configuration entry
-    time:
-      - platform: sntp
-        id: sntp_time
-
-Configuration variables:
-
-- **servers** (*Optional*, list of strings): Choose up to 3 NTP servers that are used for the clock source.
-  Defaults to ``0.pool.ntp.org``, ``1.pool.ntp.org`` and ``2.pool.ntp.org``
-- All other options from :ref:`base_time_config`.
-
-.. note::
-
-    If your are using :ref:`wifi-manual_ip` make sure to configure a DNS Server (dns1, dns2) or use only IP addresses for the NTP servers.
-
-.. warning::
-
-    Due to limitations of the SNTP implementation, this component will trigger ``on_time_sync`` only once when it detects that the
-    system clock has been set, even if the update was not done by the SNTP implementation!
-    This must be taken into consideration when SNTP is used together with other real time components, where another time source could
-    update the time before SNTP synchronizes.
-
-GPS Time Source
----------------
-
-You first need to set up the :doc:`GPS </components/gps>` component.
-
-.. code-block:: yaml
-
-    # Example configuration entry
-    time:
-      - platform: gps
-        id: gps_time
-
-Configuration variables:
-
-- All other from :ref:`base_time_config`.
-
-DS1307 Time Source
-------------------
-
-You first need to set up the :doc:`I2C </components/i2c>` component.
-
-.. code-block:: yaml
-
-    # Example configuration entry
-    time:
-      - platform: ds1307
-        id: ds1307_time
-
-Configuration variables:
-
-- **address** (*Optional*, int): Manually specify the I²C address of the RTC. Defaults to ``0x68``.
-- All other options from :ref:`base_time_config`.
-
-.. _ds1307-write_time_action:
-
-``ds1307.write_time`` Action
-****************************
-
-This :ref:`Action <config-action>` triggers a synchronization of the current system time to the RTC hardware.
-
-.. note::
-
-    The DS1307 component will *not* write the RTC clock if not triggered *explicitly* by this action.
-
-.. code-block:: yaml
-
-    on_...:
-      - ds1307.write_time
-
-      # in case you need to specify the DS1307 id
-      - ds1307.write_time:
-          id: ds1307_time
-
-.. _ds1307-read_time_action:
-
-``ds1307.read_time`` Action
-***************************
-
-This :ref:`Action <config-action>` triggers a synchronization of the current system time from the RTC hardware.
-
-.. note::
-
-    The DS1307 component will automatically read the RTC clock every 15 minutes by default and synchronize the
-    system clock when a valid timestamp was read from the RTC. (The ``update_interval`` can be changed.)
-    This action can be used to trigger *additional* synchronizations.
-
-.. code-block:: yaml
-
-    on_...:
-      - ds1307.read_time
-
-      # in case you need to specify the DS1307 id
-      - ds1307.read_time:
-          id: ds1307_time
-
-.. _ds1307-config_example:
-
-Configuration Example
-*********************
-
-In a typical setup, you will have at least one additional time source to synchronize the RTC with. Such an
-external time source might not always be available e.g. due to a limited network connection.
-In order to have a valid, reliable system time, the system should read the RTC once at start and then try to
-synchronize with an external reliable time source.
-When a synchronization to another time source was successful, the RTC can be resynchronized.
-
-.. code-block:: yaml
-
-    esphome:
-      on_boot:
-        then:
-          # read the RTC time once when the system boots
-          ds1307.read_time:
-
-    time:
-      - platform: ds1307
-        # repeated synchronization is not necessary unless the external RTC
-        # is much more accurate than the internal clock
-        update_interval: never
-      - platform: homeassistant
-        # instead try to synchronize via network repeatedly ...
-        on_time_sync:
-          then:
-            # ... and update the RTC when the synchronization was successful
-            ds1307.write_time:
 
 Use In Lambdas
 --------------
@@ -475,3 +327,9 @@ See Also
 
 - :apiref:`time/real_time_clock.h`
 - :ghedit:`Edit`
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *
diff --git a/components/time/sntp.rst b/components/time/sntp.rst
new file mode 100644
index 000000000..4da7b7fd4
--- /dev/null
+++ b/components/time/sntp.rst
@@ -0,0 +1,34 @@
+SNTP Time Source
+================
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    time:
+      - platform: sntp
+        id: sntp_time
+
+
+Configuration variables
+-----------------------
+
+- **servers** (*Optional*, list of strings): Choose up to 3 NTP servers that are used for the clock source.
+  Defaults to ``0.pool.ntp.org``, ``1.pool.ntp.org`` and ``2.pool.ntp.org``
+- All other options from :ref:`base_time_config`.
+
+.. note::
+
+    If your are using :ref:`wifi-manual_ip` make sure to configure a DNS Server (dns1, dns2) or use only IP addresses for the NTP servers.
+
+.. warning::
+
+    Due to limitations of the SNTP implementation, this component will trigger ``on_time_sync`` only once when it detects that the
+    system clock has been set, even if the update was not done by the SNTP implementation!
+    This must be taken into consideration when SNTP is used together with other real time components, where another time source could
+    update the time before SNTP synchronizes.
+
+
+See Also
+--------
+
+- :ghedit:`Edit`
diff --git a/components/tuya.rst b/components/tuya.rst
index 14f62c7de..0710fb7d7 100644
--- a/components/tuya.rst
+++ b/components/tuya.rst
@@ -66,7 +66,7 @@ Configuration variables:
 ------------------------
 
 - **time_id** (*Optional*, :ref:`config-id`): Some Tuya devices support obtaining local time from ESPHome.
-  Specify the ID of the :ref:`Time Component <time>` which will be used.
+  Specify the ID of the :doc:`time/index` which will be used.
 
 - **status_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): Some Tuya devices support WiFi status reporting ONLY through gpio pin.
   Specify the pin reported in the config dump or leave empty otherwise.
diff --git a/index.rst b/index.rst
index e72ccc8a6..8dad5e4a2 100644
--- a/index.rst
+++ b/index.rst
@@ -645,6 +645,17 @@ Media Player Components
     Media Player Core, components/media_player/index, folder-open.svg
     I2S Audio, components/media_player/i2s_audio, i2s_audio.svg
 
+Time Components
+---------------
+
+.. imgtable::
+
+    Time Core, components/time/index, clock-outline.svg
+    Home Assistant Time, components/time/homeassistant, home-assistant.svg
+    SNTP, components/time/sntp, clock-outline.svg
+    GPS Time, components/time/gps, crosshairs-gps.svg
+    DS1307 RTC, components/time/ds1307, clock-outline.svg
+
 Misc Components
 ---------------
 
@@ -658,7 +669,6 @@ Misc Components
     HTTP Request, components/http_request, connection.svg
     mDNS, components/mdns, radio-tower.svg
 
-    Time, components/time, clock-outline.svg
     Sun, components/sun, weather-sunny.svg
     GPS, components/gps, crosshairs-gps.svg