From ee389906dc86c04d9bb88b9ba3df08f59f83a902 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joakim=20S=C3=B8rensen?= Date: Mon, 1 Mar 2021 14:59:10 +0100 Subject: [PATCH] Adjust documentation for add-ons (#826) --- docs/add-ons/configuration.md | 57 +++++++++++++++++++++++++++----- docs/add-ons/repository.md | 8 ++++- docs/api/supervisor/endpoints.md | 8 +++++ 3 files changed, 64 insertions(+), 9 deletions(-) diff --git a/docs/add-ons/configuration.md b/docs/add-ons/configuration.md index cceb2df6..1819490c 100644 --- a/docs/add-ons/configuration.md +++ b/docs/add-ons/configuration.md @@ -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 +``` diff --git a/docs/add-ons/repository.md b/docs/add-ons/repository.md index d9674425..6b0a1458 100644 --- a/docs/add-ons/repository.md +++ b/docs/add-ons/repository.md @@ -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 +``` + | Key | Required | Description | | --- | -------- | ----------- | | name | yes | Name of the repository diff --git a/docs/api/supervisor/endpoints.md b/docs/api/supervisor/endpoints.md index 6efd2c13..d05a0ce0 100644 --- a/docs/api/supervisor/endpoints.md +++ b/docs/api/supervisor/endpoints.md @@ -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,