Adjust documentation for add-ons (#826)

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
+```

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 <info@home-assistant.io>
+```
+
 | Key | Required | Description |
 | --- | -------- | ----------- |
 | name | yes | Name of the repository

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,