Add a section about custom component deprecation (#4247)

components/binary_sensor/custom.rst

@@ -8,9 +8,9 @@ Custom Binary Sensor
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

components/climate/custom.rst

@@ -8,9 +8,9 @@ Custom Climate
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

components/cover/custom.rst

@@ -8,9 +8,9 @@ Custom Cover
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

components/light/custom.rst

@@ -8,9 +8,9 @@ Custom Light Output
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

components/output/custom.rst

@@ -8,9 +8,9 @@ Custom Output
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

components/sensor/bmi160.rst

@@ -7,15 +7,13 @@ BMI160 Accelerometer/Gyroscope Sensor
 
 The ``bmi160`` sensor platform allows you to use your BMI160 Accelerometer/Gyroscope
 (`datasheet <https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmi160-ds000.pdf>`__,
-`SparkFun`_) sensors with
-ESPHome. The :ref:`I²C Bus <i2c>` is
-required to be set up in your configuration for this sensor to work.
-
-This component only does some basic filtering and no calibration. Due to the complexity of
-this sensor and the amount of possible configuration options, you should probably
-create a custom component by copying and modifying the existing code if you want a specific
-new feature. Supporting all possible use-cases would be quite hard.
+`SparkFun`_) sensors with ESPHome. The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this
+sensor to work.
 
+This component only does some basic filtering and no calibration. Due to the complexity of this sensor and the amount
+of possible configuration options, you should probably create an :doc:`external component</components/external_components>`
+by copying and modifying the existing code if you want a specific new feature. Supporting all possible use cases would
+be quite hard.
 
 .. figure:: images/bmi160-full.jpg
     :align: center

components/sensor/custom.rst

@@ -8,9 +8,9 @@ Custom Sensor Component
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

components/sensor/mpu6050.rst

@@ -7,15 +7,13 @@ MPU6050 Accelerometer/Gyroscope Sensor
 
 The ``mpu6050`` sensor platform allows you to use your MPU6050 Accelerometer/Gyroscope
 (`datasheet <https://www.invensense.com/wp-content/uploads/2015/02/MPU-6000-Datasheet1.pdf>`__,
-`SparkFun`_) sensors with
-ESPHome. The :ref:`I²C Bus <i2c>` is
-required to be set up in your configuration for this sensor to work.
-
-This component only does some basic filtering and no calibration. Due to the complexity of
-this sensor and the amount of possible configuration options, you should probably
-create a custom component by copying and modifying the existing code if you want a specific
-new feature. Supporting all possible use-cases would be quite hard.
+`SparkFun`_) sensors with ESPHome. The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this
+sensor to work.
 
+This component only does some basic filtering and no calibration. Due to the complexity of this sensor and the amount
+of possible configuration options, you should probably create an :doc:`external component</components/external_components>`
+by copying and modifying the existing code if you want a specific new feature. Supporting all possible use cases would
+be quite hard.
 
 .. figure:: images/mpu6050-full.jpg
     :align: center

components/sensor/mpu6886.rst

@@ -7,14 +7,13 @@ MPU6886 Accelerometer/Gyroscope Sensor
 
 The ``mpu6886`` sensor platform allows you to use your MPU6886 Accelerometer/Gyroscope
 (`datasheet <https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/datasheet/core/MPU-6886-000193%2Bv1.1_GHIC_en.pdf>`__,
-`M5Stack`_) sensors with
-ESPHome. The :ref:`I²C Bus <i2c>` is
-required to be set up in your configuration for this sensor to work.
+`M5Stack`_) sensors with ESPHome. The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this
+sensor to work.
 
-This component only does some basic filtering and no calibration. Due to the complexity of
-this sensor and the amount of possible configuration options, you should probably
-create a custom component by copying and modifying the existing code if you want a specific
-new feature. Supporting all possible use-cases would be quite hard.
+This component only does some basic filtering and no calibration. Due to the complexity of this sensor and the amount
+of possible configuration options, you should probably create an :doc:`external component</components/external_components>`
+by copying and modifying the existing code if you want a specific new feature. Supporting all possible use cases would
+be quite hard.
 
 The MPU6886 is built-in in various M5Stack units (e.g., M5Stick C, ATOM Matrix or M5Stack Core2).
 

components/switch/custom.rst

@@ -8,9 +8,9 @@ Custom Switch
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

components/text_sensor/custom.rst

@@ -8,9 +8,9 @@ Custom Text Sensor
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

custom/custom_component.rst

@@ -8,9 +8,9 @@ Generic Custom Component
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

custom/i2c.rst

@@ -8,9 +8,9 @@ Custom I²C Device
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

custom/spi.rst

@@ -8,9 +8,9 @@ Custom SPI Device
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

custom/uart.rst

@@ -8,9 +8,9 @@ Custom UART Device
 
 .. warning::
 
-    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    :doc:`/components/external_components`.
+    :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
+    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
+    it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 

guides/contributing.rst

@@ -647,6 +647,8 @@ The C++ part of the codebase is what's actually running on the microcontroller;
 of the codebase should first set up the communication interface to a sensor/component/etc. and then communicate with
 the ESPHome core via the defined interfaces (like ``Sensor``, ``BinarySensor`` and ``Switch``, among others).
 
+.. _directory_structure:
+
 Directory Structure
 *******************
 
@@ -742,6 +744,8 @@ A few notes on validation:
   obscure shorthand. As an example, ``scrn_btn_inpt`` is indeed shorter but more difficult to understand, particularly
   for new users; avoid naming keys and variables in this way.
 
+.. _code_generation:
+
 Code Generation
 ***************
 
@@ -782,6 +786,8 @@ Next, there's a special method - ``cg.add`` - that you will often use. ``cg.add(
 C++ declared in the parentheses of ``cg.add()`` will be added to the generated code. Note that, if you do not call
 "add" to insert a piece of code explicitly, it will not be added to the ``main.cpp`` file!
 
+.. _runtime:
+
 Runtime
 *******
 
@@ -832,6 +838,66 @@ it then attempts to read back the measurement from the sensor.
 For any :apiclass:`Component` (which is nearly everything), the well-known ``set_timeout`` method is also available;
 this can be a handy alternative to implemeting a state machine.
 
+.. _a_note_about_custom_components:
+
+A Note About Custom Components
+******************************
+
+*"I read that custom components are deprecated...so now what do I do???"*
+
+ESPHome's "custom component" mechanism is a holdover from Home Assistant's feature by the same name. It existed before
+:doc:`/components/external_components` and offered a way to "hack in" support for devices which were not officially
+supported by ESPHome.
+
+ESPHome has since deprecated this feature in favor of :doc:`/components/external_components` for several reasons:
+
+- Custom components are very fragile:
+
+  - There is no validation. You can easily configure a custom component incorrectly and there will be no warning.
+  - Types are not checked. You might incorrectly pass a variable of an incorrect type or unit to a custom component
+    resulting in compiler errors, unexpected behavior and/or crashes.
+  - Custom components are difficult to use. You have to manually copy all of the custom component's files into *just
+    the right location* on your system or else you will receive compiler errors and the component won't work.
+  - Custom components almost always require C++ code changes when you want them to work even *slightly* differently
+    than the original author intended.
+
+- :doc:`/components/external_components` initially require a bit more effort by the developer but are ultimately more
+  robust and easier to use and share:
+
+  - Just like any other ESPHome component/platform:
+  
+    - They are configured entirely in YAML.
+    - Their YAML configuration is validated.
+
+  - They do not require the user to:
+
+    - Manually copy files onto their system.
+    - Touch/edit any C++ code.
+
+  - They tend to be more flexible since they are configured in YAML (as opposed to editing C++ code to make changes).
+
+**So what is the difference between custom components and** :doc:`/components/external_components`?
+
+Custom components are typically (more or less) just the :ref:`runtime` part of an ESPHome component/platform. On the
+other hand, :doc:`/components/external_components` are just like any other ESPHome component -- the only difference is
+that they are *external* in the sense that they are not "officially" a part of ESPHome.
+
+In terms of implementation, custom components just lack the Python part of an ESPHome component, specifically:
+
+- :ref:`config_validation`
+- :ref:`code_generation`
+
+As such, most custom components can be made into :doc:`/components/external_components` simply by adding the required
+Python parts to make the custom component into a proper, complete ESPHome component.
+
+We encourage all custom component developers to extend their custom component(s) into proper
+:doc:`/components/external_components`; doing so will make your custom component easier to share and use. As you do so,
+be sure to have a look at the the :ref:`contributing_to_esphome` section above as it walks through ESPHome (component)
+architecture. In addition, it's often helpful to take a look at other, similar
+`components <https://github.com/esphome/esphome/tree/dev/esphome/components>`__ and adapt them to fit the needs of your
+custom component. For common hardware devices such as :doc:`sensors</components/sensor/index>`, this is often a
+reasonably trivial exercise and `we are happy to help you along! <https://discord.gg/KhAMKrd>`__
+
 Extras
 ******
 

index.rst

@@ -1120,7 +1120,7 @@ Miscellaneous Components
 Custom Components
 -----------------
 
-**Note: Custom Components are deprecated in favor of** :doc:`components/external_components`!
+**Note:** :ref:`Custom Components are deprecated<a_note_about_custom_components>` in favor of :doc:`components/external_components`!
 
 .. imgtable::