Adjust documentation for add-ons (#826)

This commit is contained in:
Joakim Sørensen 2021-03-01 14:59:10 +01:00 committed by GitHub
parent f94db5597c
commit ee389906dc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 64 additions and 9 deletions

View File

@ -6,10 +6,12 @@ Each add-on is stored in a folder. The file structure looks like this:
```text
addon_name/
translations/
en.(json/yaml/yml)
apparmor.txt
build.json
build.(json/yaml/yml)
CHANGELOG.md
config.json
config.(json/yaml/yml)
DOCS.md
Dockerfile
icon.png
@ -71,7 +73,7 @@ If you don't use local build on device or our build script, make sure that the D
LABEL io.hass.version="VERSION" io.hass.type="addon" io.hass.arch="armhf|aarch64|i386|amd64"
```
It is possible to use own base image with `build.json` or if you do not need support for automatic multi-arch building you can also use a simple docker `FROM`.
It is possible to use own base image with `build.(json/yaml/yml)` or if you do not need support for automatic multi-arch building you can also use a simple docker `FROM`.
### Build Args
@ -80,12 +82,12 @@ We support the following build arguments by default:
| ARG | Description |
|-----|-------------|
| BUILD_FROM | Hold image for dynamic builds or buildings over our systems.
| BUILD_VERSION | Add-on version (read from `config.json`).
| BUILD_VERSION | Add-on version (read from `config.(json/yaml/yml)`).
| BUILD_ARCH | Hold current build arch inside.
## Add-on config
The configuration for an add-on is stored in `config.json`.
The configuration for an add-on is stored in `config.(json/yaml/yml)`.
```json
{
@ -101,12 +103,28 @@ The configuration for an add-on is stored in `config.json`.
"123/tcp": 123
},
"map": ["config:rw", "ssl"],
"options": {},
"schema": {},
"image": "repo/{arch}-my-custom-addon"
}
```
```yaml
name: xy
version: '1.2'
slug: folder
description: long description
arch:
- amd64
url: website with more information about add-on (e.g., a forum thread for support)
startup: application
boot: auto
ports:
123/tcp: 123
map:
- config:rw
- ssl
image: repo/{arch}-my-custom-addon
```
| Key | Type | Required | Description |
| --- | ---- | -------- | ----------- |
| name | string | yes | Name of the add-on.
@ -217,7 +235,7 @@ We support:
## Add-on extended build
Additional build options for an add-on is stored in `build.json`. This file will be read from our build systems.
Additional build options for an add-on is stored in `build.(json/yaml/yml)`. This file will be read from our build systems.
You need this only, if you not use the default images or need additional things.
```json
@ -232,6 +250,14 @@ You need this only, if you not use the default images or need additional things.
}
```
```yaml
build_from:
armhf: mycustom/base-image:latest
squash: false
args:
my_build_arg: xy
```
| Key | Required | Description |
| --- | -------- | ----------- |
| build_from | no | A dictionary with the hardware architecture as the key and the base Docker image as value.
@ -241,3 +267,18 @@ You need this only, if you not use the default images or need additional things.
We provide a set of [base images][docker-base] which should cover a lot of needs. If you don't want use the Alpine based version or need a specific image tag, feel free to pin this requirements for you build with `build_from` option.
[docker-base]: https://github.com/home-assistant/docker-base
## Add-on translations
Add-ons can provide translation files for configuration options that are used in the UI.
Example path to translation file: `addon/translations/{language_code}.(json/yaml/yml)`
For `{language_code}` use a valid language code, like `en`, for a [full list have a look here](https://github.com/home-assistant/frontend/blob/dev/src/translations/translationMetadata.json), `en.yaml` would be a valid filename.
```yaml
configuration:
ssl:
name: SSL
description: Enable usage of SSL on the webserver inside the add-on
```

View File

@ -12,7 +12,7 @@ A user can add a repository by going to the Supervisor panel in Home Assistant,
## Repository configuration
Each repository is required to contain `repository.json` at the root in the git repository.
Each repository is required to contain `repository.(json/yaml/yml)` at the root in the git repository.
```json
{
@ -22,6 +22,12 @@ Each repository is required to contain `repository.json` at the root in the git
}
```
```yaml
name: Name of repository
url: http://www.example/addons
maintainer: HomeAssistant Team <info@home-assistant.io>
```
| Key | Required | Description |
| --- | -------- | ----------- |
| name | yes | Name of the repository

View File

@ -145,6 +145,7 @@ Get details about a add-on
| startup | string | The stage when the add-on is started (initialize, system, services, application, once) |
| state | string or null | The state of the add-on (started, stopped) |
| stdin | boolean | `true` if the add-on accepts stdin commands |
| translations | dictionary | A dictionary containing content of translation files for the add-on |
| udev | boolean | `true` if udev access is granted is enabled |
| update_available | boolean | `true` if an update is available |
| url | string or null | URL to more information about the add-on |
@ -217,6 +218,13 @@ Get details about a add-on
"startup": "application",
"state": "started",
"stdin": false,
"translations": {
"en": {
"configuration": {
"lorem": "ipsum"
}
}
},
"udev": false,
"update_available": false,
"url": null,