docs-a-d: apply sentence-style capitalization to headings (#2192)

- to comply with MS Style Guide on [capitalization](https://learn.microsoft.com/en-us/style-guide/capitalization)
This commit is contained in:
c0ffeeca7 2024-05-23 09:30:17 +02:00 committed by GitHub
parent dff111c236
commit 2a1a921bcd
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
35 changed files with 66 additions and 66 deletions

View File

@ -1,5 +1,5 @@
---
title: "Python Library: Authentication"
title: "Python library: authentication"
sidebar_label: Authentication
---

View File

@ -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!

View File

@ -1,5 +1,5 @@
---
title: "Integration Architecture"
title: "Integration architecture"
sidebar_label: "Integrations"
---

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -1,5 +1,5 @@
---
title: "Asynchronous Programming"
title: "Asynchronous programming"
sidebar_label: Introduction
---

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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).

View File

@ -1,6 +1,6 @@
---
title: "Bluetooth"
sidebar_label: "Building a Bluetooth Integration"
sidebar_label: "Building a Bluetooth integration"
---
### Best practices for integration authors

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -1,5 +1,5 @@
---
title: "Integration with Multiple Platforms"
title: "Integration with multiple platforms"
sidebar_label: Multiple platforms
---

View File

@ -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/`.

View File

@ -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/<domain>`
## 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:

View File

@ -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`.

View File

@ -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.

View File

@ -1,5 +1,5 @@
---
title: "Integration Platforms"
title: "Integration platforms"
sidebar_label: "Platforms"
---

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -1,5 +1,5 @@
---
title: "Development Checklist"
title: "Development checklist"
sidebar_label: Introduction
---

View File

@ -1,5 +1,5 @@
---
title: "Set up Development Environment"
title: "Set up development environment"
---
```mdx-code-block

View File

@ -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

View File

@ -1,5 +1,5 @@
---
title: "Device Actions"
title: "Device actions"
sidebar_label: Actions
---

View File

@ -1,5 +1,5 @@
---
title: "Device Conditions"
title: "Device conditions"
sidebar_label: Conditions
---

View File

@ -1,5 +1,5 @@
---
title: "Device Automations"
title: "Device automations"
sidebar_label: Introduction
---

View File

@ -1,5 +1,5 @@
---
title: "Device Triggers"
title: "Device triggers"
sidebar_label: Triggers
---

View File

@ -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.

View File

@ -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.