Create docs for Button core, restart, template (#1681)

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

components/button/index.rst

@@ -0,0 +1,118 @@
+Button Component
+================
+
+.. seo::
+    :description: Instructions for setting up button components in ESPHome.
+    :image: folder-open.svg
+
+ESPHome has support for components to create a button entity. A button entity is
+basically a momentary switch with no state and can be triggered by either YAML or
+the user/frontend.
+
+.. note::
+
+    Home Assistant Core 2021.12 or higher is required for ESPHome button entities to work.
+
+.. _config-button:
+
+Base Button Configuration
+-------------------------
+
+All buttons in ESPHome have a name and an optional icon.
+
+.. code-block:: yaml
+
+    # Example button configuration
+    button:
+      - platform: ...
+        name: Livingroom Lazy Mood
+        id: my_button
+
+        # Optional variables:
+        icon: "mdi:emoticon-outline"
+        on_press:
+          - logger.log: "Button pressed"
+
+Configuration variables:
+
+- **name** (**Required**, string): The name for the button.
+- **icon** (*Optional*, icon): Manually set the icon to use for the button in the frontend.
+- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
+  not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
+  a ``name`` will implicitly set this to true.
+- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
+  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
+- **entity_category** (*Optional*, string): The category of the entity.
+  See https://developers.home-assistant.io/docs/core/entity/#generic-properties
+  for a list of available options. Set to ``""`` to remove the default entity category.
+
+Automations:
+
+- **on_press** (*Optional*, :ref:`Automation <automation>`): An automation to perform
+  when the button is pressed. See :ref:`button-on_press`.
+
+MQTT options:
+
+- All other options from :ref:`MQTT Component <config-mqtt-component>`.
+
+Button Automation
+-----------------
+
+.. _button-on_press:
+
+``on_press``
+************
+
+This automation will be triggered when the button is pressed.
+
+.. code-block:: yaml
+
+    button:
+      - platform: template
+        # ...
+        on_press:
+          then:
+            - logger.log: Button Pressed
+
+Configuration variables: see :ref:`Automation <automation>`.
+
+.. _button-press_action:
+
+``button.press`` Action
+***********************
+
+This is an :ref:`Action <config-action>` for pressing a button in an Automation.
+
+.. code-block:: yaml
+
+    - button.press: my_button
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the button to set.
+
+.. _button-lambda_calls:
+
+lambda calls
+************
+
+From :ref:`lambdas <config-lambda>`, you can press a button.
+
+- ``press()``: Press the button.
+
+  .. code-block:: cpp
+
+      // Within lambda, press the button.
+      id(my_button).press();
+
+See Also
+--------
+
+- :apiref:`button/button.h`
+- :ghedit:`Edit`
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *

components/button/restart.rst

@@ -0,0 +1,31 @@
+Restart Button
+==============
+
+.. seo::
+    :description: Instructions for setting up buttons that can remotely reboot the ESP in ESPHome.
+    :image: restart.svg
+
+The ``restart`` button platform allows you to restart your node remotely
+through Home Assistant.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    button:
+      - platform: restart
+        name: "Living Room Restart"
+
+Configuration variables:
+------------------------
+
+- **name** (**Required**, string): The name for the button.
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- All other options from :ref:`Button <config-button>`.
+
+See Also
+--------
+
+- :doc:`/components/switch/restart`
+- :doc:`template`
+- :apiref:`restart/button/restart_button.h`
+- :ghedit:`Edit`

components/button/template.rst

@@ -0,0 +1,32 @@
+Template Button
+===============
+
+.. seo::
+    :description: Instructions for setting up template buttons that can execute arbitrary actions when pressed.
+    :image: description.svg
+
+The ``template`` button platform allows you to create simple buttons out of just actions. Once defined,
+it will automatically appear in Home Assistant as a button and can be controlled through the frontend.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    button:
+      - platform: template
+        name: "Template Button"
+        on_press:
+          - logger.log: Button Pressed
+
+Configuration variables:
+------------------------
+
+- **name** (**Required**, string): The name of the switch.
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- All other options from :ref:`Button <config-button>`.
+
+See Also
+--------
+
+- :doc:`/guides/automations`
+- :doc:`/components/button/index`
+- :ghedit:`Edit`

components/index.rst

@@ -14,6 +14,7 @@ Components
     select/index
     sensor/index
     switch/index
+    button/index
     display/index
     text_sensor/index
     stepper/index

components/switch/restart.rst

@@ -32,5 +32,5 @@ See Also
 - :doc:`shutdown`
 - :doc:`safe_mode`
 - :doc:`template`
-- :apiref:`restart/restart_switch.h`
+- :apiref:`restart/switch/restart_switch.h`
 - :ghedit:`Edit`

index.rst

@@ -458,6 +458,15 @@ Switch Components
     BLE Client Switch, components/switch/ble_client, bluetooth.svg
     Nextion Switch, components/switch/nextion, nextion.jpg
 
+Button Components
+-----------------
+
+.. imgtable::
+
+    Button Core, components/button/index, folder-open.svg
+    Template Button, components/button/template, description.svg
+    Restart Button, components/button/restart, restart.svg
+
 Fan Components
 --------------