add External components docs (#1107)

* Add external_components

* fixes

* fix indent

* fix misplaced directive

* add full config before shorthands

* adding a bit more info

* update contributing use external components

components/external_components.rst

@@ -0,0 +1,166 @@
+External Components
+===================
+
+.. seo::
+    :description: Instructions for setting up ESPHome External Components.
+    :keywords: External, Custom, Components, ESPHome
+
+You can easily import community components using the external components feature. Bundled components
+can be overridden using this feature.
+
+.. code-block:: yaml
+
+    external_components:
+      # use rtttl and dfplayer from ESPHome's dev branch in GitHub
+      - source:
+          type: git
+          url: https://github.com/esphome/esphome
+          ref: dev
+        components: [ rtttl, dfplayer ]
+
+      # equivalent shorthand for GitHub
+      - source: github://esphome/esphome@dev
+        components: [ rtttl ]
+
+Configuration variables:
+
+- **source**: The location of the components you want to retrieve. See :ref:`external-components_local`
+  and :ref:`external-components_git`.
+
+  - **type** (**Required**): Repository type. One of ``local``, ``git``.
+
+  git options:
+
+  - **url** (**Required**, url): Http git repository url. See :ref:`external-components_git`.
+  - **ref** (*Optional*, string): Git ref (branch or tag). If not specified the default branch is used.
+
+  local options:
+
+  - **path** (**Required**):  Path to use when using local components. See :ref:`external-components_local`.
+
+- **components** (*Optional*, list): The list of components to retrieve from the external source.
+  Defaults to ``all``.
+
+- **refresh** (*Optional*, :ref:`time <config-time>`): The interval the source will be checked. Has no
+  effect on ``local``. See :ref:`external-components_refresh`. for more info. Defaults to ``1day``.
+
+
+.. _external-components_local:
+
+Local
+-----
+
+You can specify a local path for the external components, this is most useful if you want to manually
+control the origin of the files.
+
+.. code-block:: yaml
+
+    external_components:
+      source:
+        path: /copied_components
+
+    # shorthand
+    external_components:
+      source: my_components
+
+
+Notice that relative paths are supported, so you can enter ``my_components`` as the source path and then
+ESPHome will load components from a ``my_components`` folder in the same folder where your YAML configuration
+is.
+
+
+.. _external-components_git:
+
+Git
+---
+
+Retrieving components from git is the easiest way to use components not included in ESPHome by default.
+The source components should be inside a ``components`` folder or inside an ``esphome/components``
+folder. The latter makes sharing a component from a forked ESPHome repository easier.
+
+Example of git repositories
+***************************
+
+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
+    example_component1.yaml        <- not required but recommended
+    README.md
+
+
+or, this structure is also supported, which makes handy to share components from a **forked** ESPHome
+repository:
+
+.. code-block:: text
+
+    esphome
+    ├── components
+    │   ├── 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:
+
+.. code-block:: yaml
+
+    external_components:
+      source:
+        type: git
+        url: http://repository_url/
+        ref: branch_or_tag
+
+The source fields accepts a short hand **github://** resource:
+
+.. code-block:: yaml
+
+    external_components:
+      # shorthand
+      source: github://<user or org>/<repository name>[@<branch or tag>]
+
+Under the hood, during validation, ESPHome will clone the git repository into the hidden ``.esphome``
+folder and components will then be loaded from this local copy. The local path of the cloned repository
+varies per repository name and ref name, so repositories with different refs are considered different
+repositories and updated independently.
+
+.. _external-components_refresh:
+
+Refresh
+*******
+
+Components are initially cloned into a cache directory, then the repository is checked for updates
+(via *git pull*) after the ``refresh:`` time passes since last check.
+
+You can make ESPHome check the repository every time by setting this option to ``0s``, however since
+ESPHome is validating the configuration continuously while using the dashboard or the vscode extension,
+it is not recommended to set this value to less than a few minutes to avoid validation slow down and
+excessive repository checks.
+
+Likewise, you can set this setting to ``never`` and ESPHome will never
+**update** the repository, useful e.g. when ``ref`` points to a **tag**.
+
+
+See Also
+--------
+
+- :ghedit:`Edit`

guides/contributing.rst

@@ -414,10 +414,11 @@ by the integration developer.
 
 .. note::
 
-    Additionally, ESPHome has a ``custom_components`` mechanism like
-    `Home Assistant does <https://developers.home-assistant.io/docs/creating_component_index>`__.
-    So for testing you can also create a new ``custom_components`` folder inside of your ESPHome
-    config folder and create new integrations in there.
+    For testing you can use :doc:`/components/external_components`.
+
+    ESPHome also has a ``custom_components`` mechanism like `Home Assistant does
+    <https://developers.home-assistant.io/docs/creating_component_index>`__. However this is
+    discouraged in favor of :doc:`/components/external_components`.
 
 2. Config Validation
 ********************

images/external_components.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 0 24 24" width="24"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M3.9 12c0-1.7 1.4-3.1 3.1-3.1h4V7H7c-2.8 0-5 2.2-5 5s2.2 5 5 5h4v-1.9H7c-1.7 0-3.1-1.4-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.7 0 3.1 1.4 3.1 3.1s-1.4 3.1-3.1 3.1h-4V17h4c2.8 0 5-2.2 5-5s-2.2-5-5-5z"/></svg>

index.rst

@@ -85,6 +85,7 @@ Core Components
     Native API, components/api, server-network.svg
     Power Supply, components/power_supply, power.svg
     Deep Sleep, components/deep_sleep, hotel.svg
+    External Components, components/external_components, external_components.svg
 
 Sensor Components
 -----------------