diff --git a/docs/api_lib_auth.md b/docs/api_lib_auth.md index e2df30f7..708fff4b 100644 --- a/docs/api_lib_auth.md +++ b/docs/api_lib_auth.md @@ -1,5 +1,5 @@ --- -title: "Python Library: Authentication" +title: "Python library: authentication" sidebar_label: Authentication --- diff --git a/docs/api_lib_data_models.md b/docs/api_lib_data_models.md index ddf6c373..63090389 100644 --- a/docs/api_lib_data_models.md +++ b/docs/api_lib_data_models.md @@ -1,6 +1,6 @@ --- -title: "Python Library: Modelling Data" -sidebar_label: Modelling Data +title: "Python library: modelling data" +sidebar_label: Modelling data --- Now that we have authentication going, we can start making authenticated requests and fetch data! diff --git a/docs/architecture_components.md b/docs/architecture_components.md index 3e5764dc..80a5edf4 100644 --- a/docs/architecture_components.md +++ b/docs/architecture_components.md @@ -1,5 +1,5 @@ --- -title: "Integration Architecture" +title: "Integration architecture" sidebar_label: "Integrations" --- diff --git a/docs/architecture_index.md b/docs/architecture_index.md index 90928dc9..ed4522fc 100644 --- a/docs/architecture_index.md +++ b/docs/architecture_index.md @@ -1,5 +1,5 @@ --- -title: "Architecture Overview" +title: "Architecture overview" --- Home Assistant provides a platform for home control and home automation. Home Assistant is not just an application: it's an embedded system that provides an experience like other consumer off-the-shelf products: onboarding, configuration and updating is all done via an easy to use interface. diff --git a/docs/area_registry_index.md b/docs/area_registry_index.md index de3c29ad..9bbd6013 100644 --- a/docs/area_registry_index.md +++ b/docs/area_registry_index.md @@ -1,5 +1,5 @@ --- -title: Area Registry +title: Area registry --- The area registry is a registry where Home Assistant keeps track of areas. An area represents a physical location for Home Assistant. It can be used to place devices in different areas. diff --git a/docs/asyncio_categorizing_functions.md b/docs/asyncio_categorizing_functions.md index 5905cfbd..2a21eb6f 100644 --- a/docs/asyncio_categorizing_functions.md +++ b/docs/asyncio_categorizing_functions.md @@ -1,5 +1,5 @@ --- -title: "Categorizing Functions" +title: "Categorizing functions" --- A piece of work within Home Assistant is represented by a function that will be invoked. It will either run inside our event loop or inside our thread pool, depending on if it is async safe. diff --git a/docs/asyncio_index.md b/docs/asyncio_index.md index 05d6687f..3852b79a 100644 --- a/docs/asyncio_index.md +++ b/docs/asyncio_index.md @@ -1,5 +1,5 @@ --- -title: "Asynchronous Programming" +title: "Asynchronous programming" sidebar_label: Introduction --- diff --git a/docs/asyncio_thread_safety.md b/docs/asyncio_thread_safety.md index 209eb09e..61e7fa61 100644 --- a/docs/asyncio_thread_safety.md +++ b/docs/asyncio_thread_safety.md @@ -1,5 +1,5 @@ --- -title: "Thread Safety with asyncio" +title: "Thread safety with asyncio" --- Developing with asyncio requires careful attention to thread safety, as nearly all asyncio objects are not thread-safe. If you are just getting started with asyncio, review Python's documentation on [Developing with asyncio](https://docs.python.org/3/library/asyncio-dev.html) for tips to avoid pitfalls. diff --git a/docs/auth_auth_module.md b/docs/auth_auth_module.md index 4a075971..c86f0a8a 100644 --- a/docs/auth_auth_module.md +++ b/docs/auth_auth_module.md @@ -1,5 +1,5 @@ --- -title: "Multi-factor Authentication Modules" +title: "Multi-factor authentication modules" --- Multi-factor Authentication Modules are used in conjunction with [Authentication Provider](auth_auth_provider.md) to provide a fully configurable authentication framework. Each MFA module may provide one multi-factor authentication function. User can enable multiple mfa modules, but can only select one module in login process. @@ -26,7 +26,7 @@ Multi-factor Auth modules shall extend the following methods of `MultiFactorAuth | `async def async_validate(self, user_id, user_input)` | Yes | Given a user_id and user input, return validation result. | `async def async_initialize_login_mfa_step(self, user_id)` | No | Will be called once before display the mfa step of login flow. This is not initialization for the MFA module but the mfa step in login flow. -## Setup Flow +## Setup flow Before user can use a multi-factor auth module, it has to be enabled or set up. All available modules will be listed in user profile page, user can enable the module he/she wants to use. A setup data entry flow will guide user finish the necessary steps. diff --git a/docs/auth_auth_provider.md b/docs/auth_auth_provider.md index 1980db2b..fd14c134 100644 --- a/docs/auth_auth_provider.md +++ b/docs/auth_auth_provider.md @@ -1,5 +1,5 @@ --- -title: "Authentication Providers" +title: "Authentication providers" --- Authentication providers confirm the identity of users. The user proofs their identity by going through the login flow for an auth provider. The auth provider defines the login flow and can ask the user all information this needs. This will commonly be username and password but could also include a 2FA token or other challenges. diff --git a/docs/auth_index.md b/docs/auth_index.md index d2b366bb..64494e34 100644 --- a/docs/auth_index.md +++ b/docs/auth_index.md @@ -32,7 +32,7 @@ The user that is created during onboarding will be marked as "owner". The owner Users are a member of one or more groups. Group membership is how a user is granted permissions. -## Permission Policy +## Permission policy This is the permission policy that describes to which resources a group has access. For more information about permissions and policies, see [Permissions](auth_permissions.md). diff --git a/docs/bluetooth.md b/docs/bluetooth.md index d61a726a..6e2a36d8 100644 --- a/docs/bluetooth.md +++ b/docs/bluetooth.md @@ -1,6 +1,6 @@ --- title: "Bluetooth" -sidebar_label: "Building a Bluetooth Integration" +sidebar_label: "Building a Bluetooth integration" --- ### Best practices for integration authors diff --git a/docs/config_entries_config_flow_handler.md b/docs/config_entries_config_flow_handler.md index 9375354b..6acd3b70 100644 --- a/docs/config_entries_config_flow_handler.md +++ b/docs/config_entries_config_flow_handler.md @@ -1,5 +1,5 @@ --- -title: Config Flow +title: Config flow --- Integrations can be set up via the user interface by adding support for a config flow to create a config entry. Components that want to support config entries will need to define a Config Flow Handler. This handler will manage the creation of entries from user input, discovery or other sources (like Home Assistant OS). @@ -102,7 +102,7 @@ if device_unique_id: await self._async_handle_discovery_without_unique_id() ``` -### Unique ID Requirements +### Unique ID requirements A unique ID is used to match a config entry to the underlying device or API. The unique ID must be stable, should not be able to be changed by the user and must be a string. @@ -215,7 +215,7 @@ Translations for the config flow handlers are defined under the `config` key in When the translations are merged into Home Assistant, they will be automatically uploaded to [Lokalise](https://lokalise.co/) where the translation team will help to translate them in other languages. While developing locally, you will need to run `python3 -m script.translations develop` to see changes made to `strings.json` [More info on translating Home Assistant.](translations.md) -## Config Entry Migration +## Config entry migration As mentioned above - each Config Entry has a version assigned to it. This is to be able to migrate Config Entry data to new formats when Config Entry schema changes. diff --git a/docs/config_entries_index.md b/docs/config_entries_index.md index cc867ea8..632f056f 100644 --- a/docs/config_entries_index.md +++ b/docs/config_entries_index.md @@ -1,5 +1,5 @@ --- -title: Config Entries +title: Config entries --- Config Entries are configuration data that are persistently stored by Home Assistant. A config entry is created by a user via the UI. The UI flow is powered by a [config flow handler](config_entries_config_flow_handler.md) as defined by the component. Config entries can also have an extra [options flow handler](config_entries_options_flow_handler.md), also defined by the component. diff --git a/docs/config_entries_options_flow_handler.md b/docs/config_entries_options_flow_handler.md index 8b8d5ed5..cb798e85 100644 --- a/docs/config_entries_options_flow_handler.md +++ b/docs/config_entries_options_flow_handler.md @@ -1,5 +1,5 @@ --- -title: Options Flow +title: Options flow --- An integration that is configured via a config entry can expose options to the user to allow tweaking behavior of the integration, like which devices or locations should be integrated. diff --git a/docs/configuration_yaml_index.md b/docs/configuration_yaml_index.md index ec53efbe..e76c1714 100644 --- a/docs/configuration_yaml_index.md +++ b/docs/configuration_yaml_index.md @@ -1,5 +1,5 @@ --- -title: "Integration Configuration via YAML" +title: "Integration configuration via YAML" --- `configuration.yaml` is a configuration file defined by the user. It is automatically created by Home Assistant on first launch. It defines which components to load. diff --git a/docs/creating_component_code_review.md b/docs/creating_component_code_review.md index 78c9dced..92d966a7 100644 --- a/docs/creating_component_code_review.md +++ b/docs/creating_component_code_review.md @@ -1,6 +1,6 @@ --- title: "Checklist for creating a component" -sidebar_label: Component Checklist +sidebar_label: Component checklist --- A checklist of things to do when you're adding a new component. diff --git a/docs/creating_component_generic_discovery.md b/docs/creating_component_generic_discovery.md index dcbfaf0b..6b2cbb3d 100644 --- a/docs/creating_component_generic_discovery.md +++ b/docs/creating_component_generic_discovery.md @@ -1,5 +1,5 @@ --- -title: "Integration with Multiple Platforms" +title: "Integration with multiple platforms" sidebar_label: Multiple platforms --- diff --git a/docs/creating_integration_file_structure.md b/docs/creating_integration_file_structure.md index 06c56cc5..278cd5ab 100644 --- a/docs/creating_integration_file_structure.md +++ b/docs/creating_integration_file_structure.md @@ -1,6 +1,6 @@ --- -title: "Integration File Structure" -sidebar_label: "File Structure" +title: "Integration file structure" +sidebar_label: "File structure" --- Each integration is stored inside a directory named after the integration domain. The domain is a short name consisting of characters and underscores. This domain has to be unique and cannot be changed. Example of the domain for the mobile app integration: `mobile_app`. So all files for this integration are in the folder `mobile_app/`. diff --git a/docs/creating_integration_manifest.md b/docs/creating_integration_manifest.md index 9c2b9de3..842fc9d3 100644 --- a/docs/creating_integration_manifest.md +++ b/docs/creating_integration_manifest.md @@ -1,5 +1,5 @@ --- -title: "Integration Manifest" +title: "Integration manifest" sidebar_label: "Manifest" --- @@ -51,7 +51,7 @@ For core integrations, this should be omitted. The version of the integration is required for custom integrations. The version needs to be a valid version recognized by [AwesomeVersion](https://github.com/ludeeus/awesomeversion) like [CalVer](https://calver.org/) or [SemVer](https://semver.org/). -## Integration Type +## Integration type Integrations are split into multiple integration types. Each integration must provide an `integration_type` in their manifest, that describes its main @@ -85,7 +85,7 @@ or service per config entry. The website containing documentation on how to use your integration. If this integration is being submitted for inclusion in Home Assistant, it should be `https://www.home-assistant.io/integrations/` -## Issue Tracker +## Issue tracker The issue tracker of your integration, where users reports issues if they run into one. If this integration is being submitted for inclusion in Home Assistant, it should be omitted. For built-in integrations, Home Assistant will automatically generate the correct link. @@ -102,11 +102,11 @@ This option is used to specify dependencies that might be used by the integratio Built-in integrations shall only specify other built-in integrations in `after_dependencies`. Custom integrations may specify both built-in and custom integrations in `after_dependencies`. -## Code Owners +## Code owners GitHub usernames or team names of people that are responsible for this integration. You should add at least your GitHub username here, as well as anyone who helped you to write code that is being included. -## Config Flow +## Config flow Specify the `config_flow` key if your integration has a config flow to create a config entry. When specified, the file `config_flow.py` needs to exist in your integration. @@ -401,7 +401,7 @@ For example: } ``` -## Integration Quality Scale +## Integration quality scale The [Integration Quality Scale](https://www.home-assistant.io/docs/quality_scale/) scores an integration on the code quality and user experience. Each level of the quality scale consists of a list of requirements. If an integration matches all requirements, it's considered to have reached that level. @@ -415,9 +415,9 @@ We highly recommend getting your integration scored. } ``` -## IoT Class +## IoT class -The [IoT Class][iot_class] describes how an integration connects with, e.g., a device or service. For more information +The [IoT class][iot_class] describes how an integration connects with, e.g., a device or service. For more information about IoT Classes, read the blog about ["Classifying the Internet of Things"][iot_class]. The following IoT classes are accepted in the manifest: diff --git a/docs/creating_integration_tests_file_structure.md b/docs/creating_integration_tests_file_structure.md index b48affc3..70b733a0 100644 --- a/docs/creating_integration_tests_file_structure.md +++ b/docs/creating_integration_tests_file_structure.md @@ -1,6 +1,6 @@ --- -title: "Integration Tests File Structure" -sidebar_label: "Tests File Structure" +title: "Integration tests file structure" +sidebar_label: "Tests file structure" --- Tests for each integration are stored inside a directory named after the integration domain. For example, tests for the mobile app integration should be stored in `tests/components/mobile_app`. diff --git a/docs/creating_platform_code_review.md b/docs/creating_platform_code_review.md index c410fcdb..b2725896 100644 --- a/docs/creating_platform_code_review.md +++ b/docs/creating_platform_code_review.md @@ -1,6 +1,6 @@ --- title: "Checklist for creating a platform" -sidebar_label: Platform Checklist +sidebar_label: Platform checklist --- A checklist of things to do when you're adding a new platform. @@ -50,7 +50,7 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend( ) ``` -### 3. Setup Platform +### 3. Setup platform 1. Verify that the passed in configuration (user/pass/host etc.) works. 2. Group your calls to `add_entities if possible. diff --git a/docs/creating_platform_index.md b/docs/creating_platform_index.md index 97accba6..743c2092 100644 --- a/docs/creating_platform_index.md +++ b/docs/creating_platform_index.md @@ -1,5 +1,5 @@ --- -title: "Integration Platforms" +title: "Integration platforms" sidebar_label: "Platforms" --- diff --git a/docs/data_entry_flow_index.md b/docs/data_entry_flow_index.md index 7ac95b85..151e859c 100644 --- a/docs/data_entry_flow_index.md +++ b/docs/data_entry_flow_index.md @@ -1,12 +1,12 @@ --- -title: Data Entry Flow +title: Data entry flow --- Data Entry Flow is a data entry framework that is part of Home Assistant. Data entry is done via data entry flows. A flow can represent a simple login form or a multi-step setup wizard for a component. A Flow Manager manages all flows that are in progress and handles creation of new flows. Data Entry Flow is used in Home Assistant to login, create config entries, handle options flow, repair issues. -## Flow Manager +## Flow manager This is the class that manages the flows that are in progress. When instantiating one, you pass in two async callbacks: @@ -80,7 +80,7 @@ If the result type is `FlowResultType.ABORT`, the result should look like: } ``` -## Flow Handler +## Flow handler Flow handlers will handle a single flow. A flow contains one or more steps. When a flow is instantiated, the `FlowHandler.init_step` step will be called. Each step has several possible results: @@ -114,7 +114,7 @@ Data entry flows depend on translations for showing the text in the steps. It de For a more detailed explanation of `strings.json` see the [backend translation](/docs/internationalization/core) page. -### Show Form +### Show form This result type will show a form to the user to fill in. You define the current step, the schema of the data (using a mixture of voluptuous and/or [selectors](https://www.home-assistant.io/docs/blueprint/selectors/)) and optionally a dictionary of errors. @@ -139,7 +139,7 @@ class ExampleConfigFlow(data_entry_flow.FlowHandler): return self.async_show_form(step_id="init", data_schema=vol.Schema(data_schema)) ``` -#### Labels & Descriptions +#### Labels & descriptions Translations for the form are added to `strings.json` in a key for the `step_id`. That object may contain the folowing keys: @@ -171,7 +171,7 @@ The field labels and descriptions are given as a dictionary with keys correspond } ``` -#### Enabling Browser Autofill +#### Enabling browser autofill Suppose your integration is collecting form data which can be automatically filled by browsers or password managers, such as login credentials or contact information. You should enable autofill whenever possible for the best user experience and accessibility. There are two options to enable this. @@ -208,7 +208,7 @@ STEP_USER_DATA_SCHEMA = vol.Schema( ) ``` -#### Defaults & Suggestions +#### Defaults & suggestions If you'd like to pre-fill data in the form, you have two options. The first is to use the `default` parameter. This will both pre-fill the field, and act as the default value in case the user leaves the field empty. @@ -300,7 +300,7 @@ class ExampleConfigFlow(data_entry_flow.FlowHandler): ... ``` -### Create Entry +### Create entry When the result is "Create Entry", an entry will be created and passed to the parent of the flow manager. A success message is shown to the user and the flow is finished. You create an entry by passing a title, data and optionally options. The title can be used in the UI to indicate to the user which entry it is. Data and options can be any data type, as long as they are JSON serializable. Options are used for mutable data, for example a radius. Whilst Data is used for immutable data that isn't going to change in an entry, for example location data. @@ -331,7 +331,7 @@ class ExampleConfigFlow(data_entry_flow.FlowHandler): return self.async_abort(reason="not_supported") ``` -### External Step & External Step Done +### External step & external step done It is possible that a user needs to finish a config flow by doing actions on an external website. For example, setting up an integration by being redirected to an external webpage. This is commonly used by integrations that use OAuth2 to authorize a user. @@ -393,7 +393,7 @@ async def handle_result(hass, flow_id, data): return "Invalid config flow specified" ``` -### Show Progress & Show Progress Done +### Show progress & show progress done If a data entry flow step needs a considerable amount of time to finish, we should inform the user about this. @@ -453,7 +453,7 @@ class TestFlow(config_entries.ConfigFlow, domain=DOMAIN): return self.async_create_entry(title="Some title", data={}) ``` -### Show Menu +### Show menu This will show a navigation menu to the user to easily pick the next step. The menu labels can be hardcoded by specifying a dictionary of {`step_id`: `label`} or translated via `strings.json` when specifying a list. diff --git a/docs/dev_101_services.md b/docs/dev_101_services.md index 6d47e2bd..037f0ae4 100644 --- a/docs/dev_101_services.md +++ b/docs/dev_101_services.md @@ -1,6 +1,6 @@ --- -title: "Integration Services" -sidebar_label: "Custom Services" +title: "Integration services" +sidebar_label: "Custom services" --- Home Assistant provides ready-made services for a lot of things, but it doesn't always cover everything. Instead of trying to change Home Assistant, it is preferred to add it as a service under your own integration first. Once we see a pattern in these services, we can talk about generalizing them. @@ -187,7 +187,7 @@ The following example, shows how to provide icons for the `turn_on` and `turn_of ``` -## Entity Services +## Entity services Sometimes you want to provide extra services to control your entities. For example, the Sonos integration provides services to group and ungroup devices. Entity services are special because there are many different ways a user can specify entities. It can use areas, a group or a list of entities. @@ -218,7 +218,7 @@ async def custom_set_sleep_timer(entity, service_call): await entity.set_sleep_timer(service_call.data['sleep_time']) ``` -## Response Data +## Response data Services may respond to a service call with data for powering more advanced automations. There are some additional implementation requirements: @@ -271,7 +271,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool: The use of response data is meant for cases that do not fit the Home Assistant state. For example, a response stream of objects. Conversely, response data should not be used for cases that are a fit for entity state. For example, a temperature value should just be a sensor. -### Supporting Response Data +### Supporting response data Service calls are registered with a `SupportsResponse` value to indicate response data is supported. diff --git a/docs/development_catching_up.md b/docs/development_catching_up.md index 6de03f08..0f8e34a6 100644 --- a/docs/development_catching_up.md +++ b/docs/development_catching_up.md @@ -1,5 +1,5 @@ --- -title: "Catching up with Reality" +title: "Catching up with reality" --- If it's taking a while to develop your feature, and you want to catch up with what's in the current Home Assistant `dev` branch, you can use `git rebase`. This will pull the latest Home Assistant changes locally, rewind your commits, bring in the latest changes from Home Assistant, and replay all of your commits on top. diff --git a/docs/development_checklist.md b/docs/development_checklist.md index 2e9a0dac..a8886264 100644 --- a/docs/development_checklist.md +++ b/docs/development_checklist.md @@ -1,5 +1,5 @@ --- -title: "Development Checklist" +title: "Development checklist" sidebar_label: Introduction --- diff --git a/docs/development_environment.mdx b/docs/development_environment.mdx index 53c0a0a3..f1d11a5b 100644 --- a/docs/development_environment.mdx +++ b/docs/development_environment.mdx @@ -1,5 +1,5 @@ --- -title: "Set up Development Environment" +title: "Set up development environment" --- ```mdx-code-block diff --git a/docs/development_tips.md b/docs/development_tips.md index 83810032..e5492ad5 100644 --- a/docs/development_tips.md +++ b/docs/development_tips.md @@ -1,10 +1,10 @@ --- -title: "Tips and Tricks" +title: "Tips and tricks" --- This page provides some tips and tricks that may help you as a contributor to Home Assistant. The list here is by no means exhaustive, and if you pick up any additional undocumented tips and tricks, please open a PR to add them here. -## Tips and Tricks +## Tips and tricks ### Keep PRs simple diff --git a/docs/device_automation_action.md b/docs/device_automation_action.md index d53eadf0..393befb5 100644 --- a/docs/device_automation_action.md +++ b/docs/device_automation_action.md @@ -1,5 +1,5 @@ --- -title: "Device Actions" +title: "Device actions" sidebar_label: Actions --- diff --git a/docs/device_automation_condition.md b/docs/device_automation_condition.md index 4d1d4486..f183ee15 100644 --- a/docs/device_automation_condition.md +++ b/docs/device_automation_condition.md @@ -1,5 +1,5 @@ --- -title: "Device Conditions" +title: "Device conditions" sidebar_label: Conditions --- diff --git a/docs/device_automation_index.md b/docs/device_automation_index.md index 82c30510..3ea36d16 100644 --- a/docs/device_automation_index.md +++ b/docs/device_automation_index.md @@ -1,5 +1,5 @@ --- -title: "Device Automations" +title: "Device automations" sidebar_label: Introduction --- diff --git a/docs/device_automation_trigger.md b/docs/device_automation_trigger.md index 52250daf..0ff1f653 100644 --- a/docs/device_automation_trigger.md +++ b/docs/device_automation_trigger.md @@ -1,5 +1,5 @@ --- -title: "Device Triggers" +title: "Device triggers" sidebar_label: Triggers --- diff --git a/docs/device_registry_index.md b/docs/device_registry_index.md index e1d46fd6..305cb9c3 100644 --- a/docs/device_registry_index.md +++ b/docs/device_registry_index.md @@ -1,5 +1,5 @@ --- -title: Device Registry +title: Device registry --- The device registry is a registry where Home Assistant keeps track of devices. A device is represented in Home Assistant via one or more entities. For example, a battery-powered temperature and humidity sensor might expose entities for temperature, humidity and battery level. @@ -75,7 +75,7 @@ class HueLight(LightEntity): Besides device properties, `device_info` can also include `default_manufacturer`, `default_model`, `default_name`. These values will be added to the device registry if no other value is defined just yet. This can be used by integrations that know some information but not very specific. For example, a router that identifies devices based on MAC addresses. -### Manual Registration +### Manual registration Components are also able to register devices in the case that there are no entities representing them. An example is a hub that communicates with the lights. @@ -113,7 +113,7 @@ When the user clicks the delete device button for the device and confirms it, `a In `async_remove_config_entry_device` the integration should take the necessary steps to prepare for device removal and return `True` if successful. The integration may optionally act on `EVENT_DEVICE_REGISTRY_UPDATED` if that's more convenient than doing the cleanup in `async_remove_config_entry_device`. -## Categorizing to Device Info +## Categorizing to device info Device info is categorized into Link, Primary and Secondary by finding the first device info type which has all the keys of the device info. diff --git a/docs/documenting.md b/docs/documenting.md index b074fcee..1c5f6826 100644 --- a/docs/documenting.md +++ b/docs/documenting.md @@ -22,7 +22,7 @@ The easiest way to get started with development is to use Visual Studio Code wit To review the changes, open the command palette and choose ´Tasks: Run Task´ and then ´Preview´. -### Manual Environment +### Manual environment It is also possible to set up a more traditional development environment.