Add deprecation message to custom component pages (#3318)

components/binary_sensor/custom.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 This integration can be used to create custom binary sensors in ESPHome
 using the C++ (Arduino) API.
 

components/climate/custom.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 This integration can be used to create custom climate devices in ESPHome
 using the C++ (Arduino) API.
 

components/cover/custom.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 This integration can be used to create custom covers in ESPHome
 using the C++ (Arduino) API.
 

components/external_components.rst

@@ -8,6 +8,8 @@ External Components
 You can easily import community or personal components using the external components feature.
 Bundled components can be overridden using this feature.
 
+You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
+
 .. code-block:: yaml
 
     external_components:
@@ -91,15 +93,15 @@ Given the above example of ``my_components``, the folder structure must look lik
     ├── node2.yaml
     └── my_components
         ├── my_component1
-        │   ├── __init__.py
-        │   ├── component1.cpp
-        │   ├── component1.h
-        │   └── sensor.py
-        └── my_component2
-            ├── __init__.py
-            ├── component2.cpp
-            ├── component2.h
-            └── switch.py
+        │   ├── __init__.py
+        │   ├── component1.cpp
+        │   ├── component1.h
+        │   └── sensor.py
+        └── my_component2
+            ├── __init__.py
+            ├── component2.cpp
+            ├── component2.h
+            └── switch.py
 
 
 ..   _external-components_git:
@@ -119,16 +121,16 @@ For repositories where you share one or a few components:
 .. code-block:: text
 
     components
-    ├── my_component1
-    │   ├── __init__.py
-    │   ├── component1.cpp
-    │   ├── component1.h
-    │   └── sensor.py
-    └── my_component2
-        ├── __init__.py
-        ├── component2.cpp
-        ├── component2.h
-        └── switch.py
+    ├── my_component1
+    │   ├── __init__.py
+    │   ├── component1.cpp
+    │   ├── component1.h
+    │   └── sensor.py
+    └── my_component2
+        ├── __init__.py
+        ├── component2.cpp
+        ├── component2.h
+        └── switch.py
     example_component1.yaml        <- not required but recommended
     README.md
 
@@ -140,17 +142,17 @@ repository:
 
     esphome
     ├── components
-    │   ├── my_component1
-    │   │   ├── __init__.py
-    │   │   ├── component1.cpp
-    │   │   ├── component1.h
-    │   │   └── sensor.py
-    │   ├── my_component2
-    │   │   ├── __init__.py
-    │   │   ├── component2.cpp
-    │   │   ├── component2.h
-    │   │   └── switch.py
-    │  ...
+    │   ├── my_component1
+    │   │   ├── __init__.py
+    │   │   ├── component1.cpp
+    │   │   ├── component1.h
+    │   │   └── sensor.py
+    │   ├── my_component2
+    │   │   ├── __init__.py
+    │   │   ├── component2.cpp
+    │   │   ├── component2.h
+    │   │   └── switch.py
+    │  ...
     ...
 
 HTTP git repositories in general are supported with this configuration:

components/light/custom.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 This integration can be used to create custom lights in ESPHome
 using the C++ (Arduino) API.
 

components/output/custom.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 This integration can be used to create custom binary and float :doc:`outputs </components/output/index>`
 in ESPHome using the C++ (Arduino) API.
 

components/sensor/custom.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 .. seo::
     :description: Instructions for setting up Custom C++ sensors with ESPHome.
     :image: language-cpp.svg

components/switch/custom.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 This integration can be used to create custom switches in ESPHome
 using the C++ (Arduino) API.
 

components/text_sensor/custom.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 This integration can be used to create custom text sensors in ESPHome
 using the C++ (Arduino) API.
 

custom/custom_component.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 This integration can be used to create generic custom components in ESPHome
 using the C++ (Arduino) API. This integration should be used in cases where
 none of ESPHome's abstraction layers (for example the "sensor", "binary sensor",
@@ -50,8 +60,8 @@ And in YAML:
         auto my_custom = new MyCustomComponent();
         return {my_custom};
       components:
-      - id: my_custom_id 
-      
+      - id: my_custom_id
+
 
 Configuration variables:
 

custom/i2c.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 Lots of devices communicate using the I²C protocol. If you want to integrate
 a device into ESPHome that uses this protocol you can pretty much use almost
 all Arduino-based code because the ``Wire`` library is also available in ESPHome.
@@ -47,15 +57,15 @@ It may be useful to write to a register via I²C using a numerical input. For ex
         mode: box
         id: input_1
         icon: "mdi:counter"
-        
+
 We want to write this number to a ``REGISTER_ADDRESS`` on the slave device via I²C. The Arduino-based looping code shown above is modified following the guidance in :doc:`Custom Sensor Component </components/sensor/custom>`.
- 
+
 .. code-block:: cpp
 
     #include "esphome.h"
- 
+
     const uint16_t I2C_ADDRESS = 0x21;
-    const uint16_t REGISTER_ADDRESS = 0x78; 
+    const uint16_t REGISTER_ADDRESS = 0x78;
     const uint16_t POLLING_PERIOD = 15000; //milliseconds
     char temp = 20; //Initial value of the register
 
@@ -68,8 +78,8 @@ We want to write this number to a ``REGISTER_ADDRESS`` on the slave device via I
         //Add code here as needed
         Wire.begin();
         }
-  
-      void update() override {  
+
+      void update() override {
       char register_value = id(input_1).state; //Read the number set on the dashboard
       //Did the user change the input?
       if(register_value != temp){
@@ -81,7 +91,7 @@ We want to write this number to a ``REGISTER_ADDRESS`` on the slave device via I
             }
         }
     };
-        
+
 The ``Component`` class has been replaced with ``PollingComponent`` and the free-running ``loop()`` is changed to the  ``update()`` method with period set by ``POLLING_PERIOD``. The numerical value from the dashboard is accessed with its ``id`` tag and its state is set to the byte variable that we call ``register_value``.  To prevent an I²C write on every iteration, the contents of the register are stored in ``temp`` and checked for a change. Configuring the hardware with ``get_setup_priority()`` is explained in :doc:`Step 1 </components/sensor/custom>`.
 
 

custom/spi.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 Lots of devices communicate using the SPI protocol. If you want to integrate
 a device into ESPHome that uses this protocol you can pretty much use almost
 all Arduino-based code because the ``SPI`` library is also available in ESPHome.

custom/uart.rst

@@ -1,6 +1,16 @@
 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`.
+
+    You can find some basic documentation on creating your own components
+    at :ref:`contributing_to_esphome`.
+
 Lots of devices communicate using the UART protocol. If you want to integrate
 a device into ESPHome that uses this protocol you can pretty much use almost
 all Arduino-based code because ESPHome has a nice abstraction over the UART bus.

guides/contributing.rst

@@ -341,8 +341,8 @@ This is only possible for ``pip`` installs.
     git checkout -b my-new-feature
     cd ..
 
-The environment is now ready for use, but you need to activate the Python virtual environment 
-every time you are using it. 
+The environment is now ready for use, but you need to activate the Python virtual environment
+every time you are using it.
 
 .. code-block:: bash
 
@@ -413,6 +413,8 @@ a "rebase". More info `here <https://developers.home-assistant.io/docs/en/develo
     git fetch upstream dev
     git rebase upstream/dev
 
+.. _contributing_to_esphome:
+
 Contributing to ESPHome
 -----------------------
 
@@ -445,18 +447,18 @@ like this:
     ├── codegen.py
     ├── config_validation.py
     ├── components
-    │   ├── __init__.py
-    │   ├── dht12
-    │   │   ├── __init__.py
-    │   │   ├── dht12.cpp
-    │   │   ├── dht12.h
-    │   │   ├── sensor.py
-    │   ├── restart
-    │   │   ├── __init__.py
-    │   │   ├── restart_switch.cpp
-    │   │   ├── restart_switch.h
-    │   │   ├── switch.py
-    │  ...
+    │   ├── __init__.py
+    │   ├── dht12
+    │   │   ├── __init__.py
+    │   │   ├── dht12.cpp
+    │   │   ├── dht12.h
+    │   │   ├── sensor.py
+    │   ├── restart
+    │   │   ├── __init__.py
+    │   │   ├── restart_switch.cpp
+    │   │   ├── restart_switch.h
+    │   │   ├── switch.py
+    │  ...
 
 As you can see, all components are in the "components" folder. Each component is in its own
 subfolder which contains the Python code (.py) and the C++ code (.h and .cpp).