diff --git a/docs/api/native-app-integration/notifications.md b/docs/api/native-app-integration/notifications.md index 39d06527..d5267bf0 100644 --- a/docs/api/native-app-integration/notifications.md +++ b/docs/api/native-app-integration/notifications.md @@ -2,7 +2,7 @@ title: "Push Notifications" --- -The `mobile_app` component has a notify platform built in that allows for a generic way to send push notifications to your users without requiring installation of an external custom component. Push notifications can either be delivered via a websocket connection or via a cloud service. +The `mobile_app` integration has a notify platform built in that allows for a generic way to send push notifications to your users without requiring installation of an external custom component. Push notifications can either be delivered via a websocket connection or via a cloud service. ## Enabling websocket push notifications diff --git a/docs/api/native-app-integration/sending-data.md b/docs/api/native-app-integration/sending-data.md index 4299942a..7463f8c4 100644 --- a/docs/api/native-app-integration/sending-data.md +++ b/docs/api/native-app-integration/sending-data.md @@ -106,11 +106,11 @@ Here are the libraries we suggest using, although you should feel free to use wh - Swift/Objective-C: [swift-sodium](https://github.com/jedisct1/swift-sodium) (official library maintained by Sodium developers). -For other languages, please see the list of [Bindings for other languages](https://download.libsodium.org/doc/bindings_for_other_languages). If more than one choice is available, we recommend using the choice most recently updated as well as most peer reviewed (a easy way to check this is seeing how many GitHub stars a project has). +For other languages, please see the list of [Bindings for other languages](https://doc.libsodium.org/bindings_for_other_languages). If more than one choice is available, we recommend using the choice most recently updated as well as most peer reviewed (a easy way to check this is seeing how many GitHub stars a project has). ### Configuration -We use the [secret-key cryptography](https://download.libsodium.org/doc/secret-key_cryptography) features of Sodium to encrypt and decrypt payloads. All payloads are JSON encoded in Base64. For Base64 type, use `sodium_base64_VARIANT_ORIGINAL` (that is, "original", no padding, not URL safe). If the payload does not contain a `data` key when unencrypted (such as with the [get_config](https://developers.home-assistant.io/docs/api/native-app-integration/sending-data#get-config) request), an empty JSON object (`{}`) must be encrypted instead. +We use the [secret-key cryptography](https://doc.libsodium.org/secret-key_cryptography) features of Sodium to encrypt and decrypt payloads. All payloads are JSON encoded in Base64. For Base64 type, use `sodium_base64_VARIANT_ORIGINAL` (that is, "original", no padding, not URL safe). If the payload does not contain a `data` key when unencrypted (such as with the [get_config](https://developers.home-assistant.io/docs/api/native-app-integration/sending-data#get-config) request), an empty JSON object (`{}`) must be encrypted instead. ### Signaling encryption support diff --git a/docs/api/native-app-integration/sensors.md b/docs/api/native-app-integration/sensors.md index 1b543ba2..c7d11085 100644 --- a/docs/api/native-app-integration/sensors.md +++ b/docs/api/native-app-integration/sensors.md @@ -2,7 +2,7 @@ title: "Sensors" --- -The `mobile_app` component supports exposing custom sensors that can be managed entirely via your app. +The `mobile_app` integration supports exposing custom sensors that can be managed entirely via your app. ## Registering a sensor @@ -36,7 +36,7 @@ The valid keys are: | Key | Type | Required | Description | |---------------------|-------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | attributes | object | No | Attributes to attach to the sensor | -| device_class | string | No | One of the valid device classes. [Binary Sensor Classes](https://www.home-assistant.io/components/binary_sensor/#device-class), [Sensor Classes](https://www.home-assistant.io/components/sensor/#device-class) | +| device_class | string | No | One of the valid device classes. [Binary Sensor Classes](https://www.home-assistant.io/integrations/binary_sensor/#device-class), [Sensor Classes](https://www.home-assistant.io/integrations/sensor/#device-class) | | icon | Material Design Icon (string) | No | Must be prefixed `mdi:`. If not provided, default value is `mdi:cellphone` | | name | string | Yes | The name of the sensor | | state | bool, float, int, string | Yes | The state of the sensor | diff --git a/docs/api/native-app-integration/setup.md b/docs/api/native-app-integration/setup.md index 07ce728a..a88b099a 100644 --- a/docs/api/native-app-integration/setup.md +++ b/docs/api/native-app-integration/setup.md @@ -6,11 +6,11 @@ When a user first opens the app, they will need to connect to their local instan ## Authenticating the user -The local instance can be discovered if Home Assistant has the [zeroconf component] configured by searching for `_home-assistant._tcp.local.`. If not configured, the user will need to be asked for the local address of their instance. +The local instance can be discovered if Home Assistant has the [zeroconf integration] configured by searching for `_home-assistant._tcp.local.`. If not configured, the user will need to be asked for the local address of their instance. When the address of the instance is known, the app will ask the user to authenticate via [OAuth2 with Home Assistant]. Home Assistant uses IndieAuth, which means that to be able to redirect to a url that triggers your app, you need to take some extra steps. Make sure to read the last paragraph of the "Clients" section thoroughly. -[zeroconf component]: https://www.home-assistant.io/components/zeroconf +[zeroconf integration]: https://www.home-assistant.io/integrations/zeroconf [OAuth2 with Home Assistant]: auth_api.md ## Registering the device @@ -19,13 +19,13 @@ _This requires Home Assistant 0.90 or later._ Home Assistant has a `mobile_app` component that allows applications to register themselves and interact with the instance. This is a generic component to handle most common mobile application tasks. This component is extendable with custom interactions if your app needs more types of interactions than are offered by this component. -Once you have tokens to authenticate as a user, it's time to register the app with the mobile app component in Home Assistant. +Once you have tokens to authenticate as a user, it's time to register the app with the mobile app integration in Home Assistant. ### Getting Ready -First, you must ensure that the `mobile_app` component is loaded. There are two ways to do this: +First, you must ensure that the `mobile_app` integration is loaded. There are two ways to do this: -- You can publish a Zeroconf/Bonjour record `_hass-mobile-app._tcp.local.` to trigger the automatic load of the `mobile_app` component. You should wait at least 60 seconds after publishing the record before continuing. +- You can publish a Zeroconf/Bonjour record `_hass-mobile-app._tcp.local.` to trigger the automatic load of the `mobile_app` integration. You should wait at least 60 seconds after publishing the record before continuing. - You can ask the user to add `mobile_app` to their configuration.yaml and restart Home Assistant. If the user already has `default_config` in their configuration, then `mobile_app` will have been already loaded. You can confirm the `mobile_app` component has been loaded by checking the `components` array of the [`/api/config` REST API call](/api/rest.md#get-apiconfig). If you continue to device registration and receive a 404 status code, then it most likely hasn't been loaded yet. diff --git a/docs/api/rest.md b/docs/api/rest.md index a1e399ac..88f18b85 100644 --- a/docs/api/rest.md +++ b/docs/api/rest.md @@ -23,7 +23,7 @@ curl \ http://IP_ADDRESS:8123/ENDPOINT ``` -Another option is to use Python and the [Requests](https://requests.readthedocs.io/en/master/) module. +Another option is to use Python and the [Requests](https://requests.readthedocs.io/en/latest/) module. ```python from requests import get diff --git a/docs/development_catching_up.md b/docs/development_catching_up.md index 0200753d..6de03f08 100644 --- a/docs/development_catching_up.md +++ b/docs/development_catching_up.md @@ -42,4 +42,4 @@ You will have to start over the git fetch and rebase process described above, or git push origin --force ``` -Other workflows are covered in detail in the [Github documentation](https://help.github.com/articles/fork-a-repo/). +Other workflows are covered in detail in the [Github documentation](https://docs.github.com/get-started/quickstart/fork-a-repo). diff --git a/docs/development_checklist.md b/docs/development_checklist.md index 66dbf3bb..a6f7b3f1 100644 --- a/docs/development_checklist.md +++ b/docs/development_checklist.md @@ -5,13 +5,13 @@ sidebar_label: Introduction Before you commit any changes, check your work against these requirements: -- All communication to external devices or services must be wrapped in an external Python library hosted on [pypi](https://pypi.python.org/pypi). +- All communication to external devices or services must be wrapped in an external Python library hosted on [pypi](https://pypi.org/). - Issue trackers must be enabled for external Python libraries that has communication with external devices or services. - If the library is mainly used for Home Assistant and you are a code owner of the integration it is encouraged to use an issue template picker with links to [Home Assistant Core Issues](https://github.com/home-assistant/core/issues). For example: [zwave-js-server-python - New Issue](https://github.com/home-assistant-libs/zwave-js-server-python/issues/new/choose) - New dependencies are added to `requirements_all.txt` (if applicable), using `python3 -m script.gen_requirements_all` - New codeowners are added to `CODEOWNERS` (if applicable), using `python3 -m script.hassfest` - The `.coveragerc` file is updated to exclude your platform if there are no tests available or your new code uses a third-party library for communication with the device, service, or sensor. `config_flow.py` can't be excluded as it must be fully tested (100% coverage). - The `.strict-typing` file is updated to include your code if it does provide a fully type hinted source. -- The code is formatted using Black, as per these [guidelines](https://developers.home-assistant.io/blog/2019/07/31/black.html). This can be done running the command `black --fast homeassistant tests`. +- The code is formatted using Black, as per these [guidelines](https://developers.home-assistant.io/blog/2019/07/31/black/). This can be done running the command `black --fast homeassistant tests`. - Documentation is developed for [home-assistant.io](https://home-assistant.io/) - Visit the [website documentation](/documenting.md) for more information about contributing to [home-assistant.io](https://github.com/home-assistant/home-assistant.io). diff --git a/docs/development_environment.mdx b/docs/development_environment.mdx index 8d80245c..dd496d71 100644 --- a/docs/development_environment.mdx +++ b/docs/development_environment.mdx @@ -19,7 +19,7 @@ You'll need to set up a development environment if you want to develop a new fea ## Developing with Visual Studio Code + devcontainer -The easiest way to get started with development is to use Visual Studio Code with devcontainers. This approach will create a preconfigured development environment with all the tools you need. This approach is enabled for all Home Assistant repositories. [Learn more about devcontainers.](https://code.visualstudio.com/docs/remote/containers) +The easiest way to get started with development is to use Visual Studio Code with devcontainers. This approach will create a preconfigured development environment with all the tools you need. This approach is enabled for all Home Assistant repositories. [Learn more about devcontainers.](https://code.visualstudio.com/docs/devcontainers/containers) **Prerequisites** @@ -67,7 +67,7 @@ sudo apt-get install python3-pip python3-dev python3-venv autoconf libssl-dev li ### Developing on Windows -To develop on Windows, you will need to use the Linux subsystem (WSL). Follow the [WSL installation instructions](https://docs.microsoft.com/windows/wsl/install) and install Ubuntu from the Windows Store. Once you're able to access Linux, follow the Linux instructions. +To develop on Windows, you will need to use the Linux subsystem (WSL). Follow the [WSL installation instructions](https://learn.microsoft.com/windows/wsl/install) and install Ubuntu from the Windows Store. Once you're able to access Linux, follow the Linux instructions. :::tip If you find that you cannot open the development instance via when using WSL, instead, within a WSL terminal, find the `inet` address of the `eth0` adaptor by running `ip addr show eth0`. Then use this address, excluding the CIDR block, to access the development instance, i.e. if your `inet` is listed as `172.20.37.6/20`, use . diff --git a/docs/development_guidelines.md b/docs/development_guidelines.md index 5f2b0101..54e8cb19 100644 --- a/docs/development_guidelines.md +++ b/docs/development_guidelines.md @@ -2,21 +2,21 @@ title: "Style guidelines" --- -Home Assistant enforces quite strict [PEP8 style](https://www.python.org/dev/peps/pep-0008/) and [PEP 257 (Docstring Conventions)](https://www.python.org/dev/peps/pep-0257/) compliance on all code submitted. +Home Assistant enforces quite strict [PEP8 style](https://peps.python.org/pep-0008/) and [PEP 257 (Docstring Conventions)](https://peps.python.org/pep-0257/) compliance on all code submitted. We use [Black](https://github.com/psf/black) for uncompromised code formatting. Every pull request is automatically checked as part of the linting process and we never merge submissions that diverge. Summary of the most relevant points: - Comments should be full sentences and end with a period. -- [Imports](https://www.python.org/dev/peps/pep-0008/#imports) should be ordered. +- [Imports](https://peps.python.org/pep-0008/#imports) should be ordered. - Constants and the content of lists and dictionaries should be in alphabetical order. It is advisable to adjust IDE or editor settings to match those requirements. ## Our recommendations -For some cases [PEPs](https://www.python.org/dev/peps/) don't make a statement. This section covers our recommendations about the code style. Those points were collected from the existing code and based on what contributors and developers were using the most. This is basically a majority decision, thus you may not agree with it. But we would like to encourage you follow those recommendations to keep the code consistent. +For some cases [PEPs](https://peps.python.org/) don't make a statement. This section covers our recommendations about the code style. Those points were collected from the existing code and based on what contributors and developers were using the most. This is basically a majority decision, thus you may not agree with it. But we would like to encourage you follow those recommendations to keep the code consistent. ### File headers @@ -43,7 +43,7 @@ Also note that `_LOGGER.info` is reserved for the core, use `_LOGGER.debug` for ### Ordering of imports -Instead of ordering the imports manually, use [`isort`](https://github.com/timothycrosley/isort). +Instead of ordering the imports manually, use [`isort`](https://github.com/PyCQA/isort). ```shell pip3 install isort diff --git a/docs/development_submitting.md b/docs/development_submitting.md index 9912c734..82884143 100644 --- a/docs/development_submitting.md +++ b/docs/development_submitting.md @@ -6,7 +6,7 @@ title: "Submit your work" Always base your Pull Requests off of the current **`dev`** branch, not `master`. ::: -Submit your improvements, fixes, and new features to Home Assistant one at a time, using GitHub [Pull Requests](https://help.github.com/articles/using-pull-requests). Here are the steps: +Submit your improvements, fixes, and new features to Home Assistant one at a time, using GitHub [Pull Requests](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). Here are the steps: 1. From your fork's dev branch, create a new branch to hold your changes: @@ -33,7 +33,7 @@ Submit your improvements, fixes, and new features to Home Assistant one at a tim `git push origin HEAD` -6. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your pull request. +6. Follow [these steps](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to create your pull request. - On GitHub, navigate to the [main page of the Home Assistant repository](https://github.com/home-assistant/core). - In the "Branch" menu, choose the branch that contains your commits (from your fork). diff --git a/docs/documenting.md b/docs/documenting.md index 0f8f7aef..27742e95 100644 --- a/docs/documenting.md +++ b/docs/documenting.md @@ -4,7 +4,7 @@ title: "Documentation" The user documentation is located at [https://www.home-assistant.io](https://www.home-assistant.io). This section is the place where we provide documentation and additional details about creating or modifying content. -The [home-assistant.io](https://home-assistant.io) website is built using [Jekyll](http://github.com/mojombo/jekyll) and [these dependencies](https://pages.github.com/versions/). The pages are written in [Markdown](http://daringfireball.net/projects/markdown/). To add a page, you don't need to know HTML. +The [home-assistant.io](https://home-assistant.io) website is built using [Jekyll](https://github.com/jekyll/jekyll) and [these dependencies](https://pages.github.com/versions/). The pages are written in [Markdown](https://daringfireball.net/projects/markdown/). To add a page, you don't need to know HTML. ## Small changes diff --git a/docs/documenting/standards.md b/docs/documenting/standards.md index 908e84b9..ded9b9b0 100644 --- a/docs/documenting/standards.md +++ b/docs/documenting/standards.md @@ -6,7 +6,7 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo ## General Documentation -Broadly speaking documentation should be written following Microsoft's house style, which is detailed [here](https://docs.microsoft.com/en-us/style-guide). +Broadly speaking documentation should be written following Microsoft's house style, which is detailed [here](https://learn.microsoft.com/style-guide/welcome/). - The language of the documentation should be American-English. - Don't put two spaces after a period. diff --git a/docs/frontend/custom-ui/custom-view.md b/docs/frontend/custom-ui/custom-view.md index 4fc0c651..f47da0ce 100644 --- a/docs/frontend/custom-ui/custom-view.md +++ b/docs/frontend/custom-ui/custom-view.md @@ -6,7 +6,7 @@ By default Home Assistant will try to show the cards in a masonry layout (like P ## API -You define your custom view as a [custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). It's up to you to decide how to render your DOM inside your element. You can use Lit Element, Preact, or any other popular framework (except for React – [more info on React here](https://custom-elements-everywhere.com/#react)). +You define your custom view as a [custom element](https://developer.mozilla.org/docs/Web/Web_Components/Using_custom_elements). It's up to you to decide how to render your DOM inside your element. You can use Lit Element, Preact, or any other popular framework (except for React – [more info on React here](https://custom-elements-everywhere.com/#react)). Custom Views receive the following: