Add content (#6)

Author: kbx81

.gitignore

@@ -1,3 +1,4 @@
+.DS_Store
 .cache/
 .docsite
 *.pyc

docs/architecture/components/alarm_control_panel.md

@@ -0,0 +1 @@
+# Alarm Control Panel

docs/architecture/components/binary_sensor.md

@@ -1 +1 @@
-# Sensor
+# Binary Sensor

docs/architecture/components/button.md

@@ -0,0 +1 @@
+# Button

docs/architecture/components/climate.md

@@ -1 +1 @@
-# Sensor
+# Climate

docs/architecture/components/cover.md

@@ -1 +1 @@
-# Sensor
+# Cover

docs/architecture/components/display.md

@@ -0,0 +1 @@
+# Display

docs/architecture/components/event.md

@@ -0,0 +1 @@
+# Event

docs/architecture/components/fan.md

@@ -0,0 +1 @@
+# Fan

docs/architecture/components/index.md

@@ -1,8 +1,13 @@
-# ESPHome Component Architecture
+# Component Architecture
 
+All components within ESPHome have a specific structure. This structure exists because:
 
+- It allows the Python parts of ESPHome to:
+    - Easily determine which parts of the C++ codebase are required to complete a build.
+    - Understand how to interact with the component/platform so it can be configured correctly.
+- It makes understanding and maintaining the codebase easier.
 
-## Directory Structure
+## Directory structure
 
 ```
 esphome
@@ -13,8 +18,8 @@ esphome
 │ │ ├─ example_component.cpp
 ```
 
-This is the most basic component directory structure where the component would be used at the 
-top-level of the YAML configuration.
+This is the most basic component directory structure where the component would be used at the top-level of the YAML
+configuration.
 
 ```yaml
 example_component:
@@ -27,9 +32,9 @@ example_component:
 
 At the heart of every ESPHome component is the `CONFIG_SCHEMA` and the `to_code` method.
 
-The `CONFIG_SCHEMA` is based on and extends [Voluptuous](https://github.com/alecthomas/voluptuous), which is a 
-data validation library. This allows the YAML to be parsed and converted to a Python object and performs
-strong validation against the data types to ensure they match.
+The `CONFIG_SCHEMA` is based on and extends [Voluptuous](https://github.com/alecthomas/voluptuous), which is a data
+validation library. This allows the YAML to be parsed and converted to a Python object and performs strong validation
+against the data types to ensure they match.
 
 ```python
 import esphome.config_validation as cv
@@ -73,26 +78,25 @@ import esphome.config_validation as cv
 import esphome.codegen as cg
 ```
 
-`config_validation` is a module that contains all the common validation functions that are used to validate the configuration.
-Components may contain their own validations as well and this is very extensible.
-`codegen` is a module that contains all the code generation functions that are used to generate the C++ code that is placed
-into `main.cpp`.
+`config_validation` is a module that contains all the common validation method that are used to validate the
+configuration. Components may contain their own validations as well and this is very extensible. `codegen` is a module
+that contains all the code generation method that are used to generate the C++ code that is placed into `main.cpp`.
 
 
 ```python
 example_component_ns = cg.esphome_ns.namespace("example_component")
 ```
 
-This is the c++ namespace inside the `esphome` namespace. It is required here so that the codegen knows the exact 
+This is the C++ namespace inside the `esphome` namespace. It is required here so that the codegen knows the exact
 namespace of the class that is being created. The namespace **must** match the name of the component.
 
 
 ```python
 ExampleComponent = example_component_ns.class_("ExampleComponent", cg.Component)
 ```
 
-This is the class that is being created. The first argument is the name of the class, the second and subsequent 
-arguments are the base classes that this class inherits from.
+This is the class that is being created. The first argument is the name of the class and any subsequent arguments are
+the base classes that this class inherits from.
 
 #### Configuration validation
 
@@ -113,10 +117,10 @@ specify their own `id` in their configuration in the event that they wish to ref
 
 #### Code generation
 
-The `to_code` method is called after the entire configuration has been validated. This function is given the
-parsed `config` object for this instance of this component. This method is responsible for generating the
-C++ code that is placed into `main.cpp` translates the user configuration into the C++ instance method calls,
-setting the variables on the object.
+The `to_code` method is called after the entire configuration has been validated. It is given the parsed `config`
+object for this instance of this component and uses it to determine exactly what C++ code is placed into the generated
+`main.cpp` file. It translates the user configuration into the C++ instance method calls, setting variables on the
+object as required/specified.
 
 ```python
 var = cg.new_Pvariable(config[CONF_ID])
@@ -131,12 +135,12 @@ constructor of the class.
 await cg.register_component(var, config)
 ```
 
-This line generates `App.register_component(var)` in C++ which registers the component so that its `setup`, `loop` and/or `update`
-functions are called correctly.
+This line generates `App.register_component(var)` in C++ which registers the component so that its `setup`, `loop`
+and/or `update` methods are called correctly.
 
 Assuming the user has `foo: true` in their YAML configuration, this line:
 
-```python 
+```python
 cg.add(var.set_foo(config[CONF_FOO]))
 ```
 
@@ -158,24 +162,26 @@ If the config value is not set, then we do not call the setter function.
 
 ### Further information
 
-- `AUTO_LOAD` - A list of components that will be automatically loaded if they are not already specified in the configuration.
-  This can be a method that can be run with access to the `CORE` information like the target platform.
-- `CODEOWNERS` - A list of GitHub usernames that are responsible for this component. `script/build_codeowners.py` will 
+- `AUTO_LOAD`: A list of components that will be automatically loaded if they are not already specified in the
+  configuration. This can be a method that can be run with access to the `CORE` information like the target platform.
+- `CONFLICTS_WITH`: A list of components which conflict with this component. If the user has one of them in their
+  config, a validation error will be generated.
+- `CODEOWNERS`: A list of GitHub usernames that are responsible for this component. `script/build_codeowners.py` will
   update the `CODEOWNERS` file.
-- `DEPENDENCIES` - A list of components that this component depends on. If these components are not present in the configuration,
-  validation will fail and the user will be shown an error.
-- `MULTI_CONF` - If set to `True`, the user can use this component multiple times in their configuration. If set to a 
+- `DEPENDENCIES`: A list of components that this component depends on. If these components are not present in the
+   configuration, validation will fail and the user will be shown an error.
+- `MULTI_CONF`: If set to `True`, the user can use this component multiple times in their configuration. If set to a
   number, the user can use this component that number of times.
-- `MULTI_CONF_NO_DEFAULT` - This is a special flag that allows the component to be auto-loaded without an instance of the configuration.
-  An example of this is the `uart` component. This component can be auto-loaded so that all of the uart headers will be available but
-  potentially there is no native uart instance, but one provided by another component such an an external i2c UART expander.
-
+- `MULTI_CONF_NO_DEFAULT`: This is a special flag that allows the component to be auto-loaded without an instance of
+  the configuration. An example of this is the `uart` component. This component can be auto-loaded so that all of the
+  UART headers will be available but potentially there is no native UART instance, but one provided by another
+  component such an an external i2c UART expander.
 
 ### Final validation
 
-ESPHome has a mechanism to run a final validation step after all of the configuration is initially deemed to be individually valid.
-This final validation gives an instance of a component the ability to check the configuration of any other components and potentially fail
-the validation stage if an important dependent configuration does not match. 
+ESPHome has a mechanism to run a final validation step after all of the configuration is initially deemed to be
+individually valid. This final validation gives an instance of a component the ability to check the configuration of
+any other components and potentially fail the validation stage if an important dependent configuration does not match.
 
-For example many components that rely on `uart` can use the `FINAL_VALIDATE_SCHEMA` to ensure that the `tx_pin` and/or `rx_pin` are 
-configured.
+For example many components that rely on `uart` can use the `FINAL_VALIDATE_SCHEMA` to ensure that the `tx_pin` and/or
+`rx_pin` are configured.