[enh] document yunohost arguments format

packaging_apps_actions.md

@@ -45,6 +45,11 @@ writing your manifest for the application installation.
 You need to write an `actions.toml` file in your application at the root level
 like the `manifest.toml`/`manifest.json`.
 
+<div class="alert alert-info">
+The arguments are written in **[YunoHost Arguments
+Format](#/packaging_apps_arguments_format)** like in `manifest.toml/json`
+</div>
+
 The general pattern looks like this:
 
 ```toml

packaging_apps_arguments_format.md

@@ -0,0 +1,298 @@
+# YunoHost Arguments Format
+
+In YunoHost application developpement there are several places where you end up
+writting questions for your user like in the `manifest.javascript/toml`, the
+`config_panel.javascript/toml` or `actions.json/toml`.
+
+This page documents this format and all available kind of questions you can ask
+your user. Unless it's stated otherwise, this format applies to everyplace it's
+usable (for now: installation arguments in `manifest.javascript/toml`,
+`config_panel.javascript/toml` and `actions.json/toml`)
+
+## YunoHost arguments general format
+
+The general format for an argument looks like this in toml:
+
+```toml
+[maybe.some.stuff.before.the_name]
+type = "one_of_the_available_type"
+ask.en = "the question in english"
+ask.fr = "the question in french"
+help.en = "some help text in english" # optional
+help.fr = "some help text in french" # optional
+example = "an example value" # optional
+default = "some stuff" # optional, not available for all types
+```
+
+And in javascript:
+
+```javascript
+{
+    "name": "the_name",
+    "type": "one_of_the_available_type",  # "sting" is not specified
+    "ask": {
+        "en": "the question in english",
+        "fr": "the question in french"
+    },
+    "help": {
+        "en": "some help text in english",
+        "fr": "some help text in french"
+    }
+    "default", "some stuff", # optional, not available for all types
+    "example": "an example value" # optional
+},
+```
+
+## All avaiable types
+
+### string
+
+This one is the simpliest one and is the default type if you don't specify one.
+
+Example in toml:
+
+```toml
+[maybe.some.stuff.before.the_name]
+type = "string"  # optional
+ask.en = "the question in english"
+ask.fr = "the question in french"
+example = "an example value"  # optional
+default = "some stuff" # optional
+```
+
+And in javascript:
+
+```javascript
+{
+    "name": "the_name",
+    "type": "string",  # optional
+    "ask": {
+        "en": "the question in english",
+        "fr": "the question in french"
+    },
+    "default": "some stuff", # optional
+    "example": "an example value"
+},
+```
+
+### string with choices
+
+Like string except the user needs to chose in a list of specifics strings.
+
+Example in toml:
+
+```toml
+[maybe.some.stuff.before.the_name]
+type = "string"
+ask.en = "the question in english"
+ask.fr = "the question in french"
+example = "an example value"  # optional
+choices = ["fr", "en"]
+default = "en" # optional
+```
+
+And in javascript:
+
+```javascript
+{
+    "name": "the_name",
+    "type": "string",
+    "ask": {
+        "en": "the question in english",
+        "fr": "the question in french"
+    },
+    "example": "an example value",
+    "choices": ["fr", "en"],
+    "default": "en" # optional
+},
+```
+
+### domain
+
+This type will ask the user to chose one of the domains of their YunoHost instance.
+
+Example in toml:
+
+```toml
+[maybe.some.stuff.before.the_name]
+type = "domain"
+ask.en = "the question in english"
+ask.fr = "the question in french"
+```
+
+And in javascript:
+
+```javascript
+{
+    "name": "the_name",
+    "type": "domain",
+    "ask": {
+        "en": "the question in english",
+        "fr": "the question in french"
+    }
+},
+```
+
+### Path
+
+This type will ask the user to chose an url path (generally to happen it to a
+domain) like "/path/to/my/app"
+
+Example in toml:
+
+```toml
+[maybe.some.stuff.before.the_name]
+type = "path"
+ask.en = "the question in english"
+ask.fr = "the question in french"
+default = "/my_app"
+```
+
+And in javascript:
+
+```javascript
+{
+    "name": "the_name",
+    "type": "path",
+    "ask": {
+        "en": "the question in english",
+        "fr": "the question in french"
+    },
+    "default": "/my_app"
+},
+```
+
+### User
+
+This type will ask the user to select a user in the list of users in their
+YunoHost installation. Generally this is used to select who is going to be the
+admin or who is going to have access to this application.
+
+Example in toml:
+
+```toml
+[maybe.some.stuff.before.the_name]
+type = "user"
+ask.en = "the question in english"
+ask.fr = "the question in french"
+```
+
+And in javascript:
+
+```javascript
+{
+    "name": "the_name",
+    "type": "user",
+    "ask": {
+        "en": "the question in english",
+        "fr": "the question in french"
+    }
+},
+```
+
+### Password
+
+This type will ask the user to input a password. This is generally used to
+input the password for creating an account on the application.
+
+Example in toml:
+
+```toml
+[maybe.some.stuff.before.the_name]
+type = "password"
+ask.en = "the question in english"
+ask.fr = "the question in french"
+```
+
+And in javascript:
+
+```javascript
+{
+    "name": "the_name",
+    "type": "password",
+    "ask": {
+        "en": "the question in english",
+        "fr": "the question in french"
+    }
+},
+```
+
+### Boolean
+
+This type will ask the user to answer true or false to a question.
+
+Example in toml:
+
+```toml
+[maybe.some.stuff.before.the_name]
+type = "boolean"
+ask.en = "the question in english"
+ask.fr = "the question in french"
+default = true
+```
+
+And in javascript:
+
+```javascript
+{
+    "name": "the_name",
+    "type": "boolean",
+    "ask": {
+        "en": "the question in english",
+        "fr": "the question in french"
+    },
+    "default": true
+},
+```
+
+### App
+
+This type will ask the user to select an application in the list of installed
+application on their YunoHost.
+
+Example in toml:
+
+```toml
+[maybe.some.stuff.before.the_name]
+type = "app"
+ask.en = "the question in english"
+ask.fr = "the question in french"
+```
+
+And in javascript:
+
+```javascript
+{
+    "name": "the_name",
+    "type": "app",
+    "ask": {
+        "en": "the question in english",
+        "fr": "the question in french"
+    }
+},
+```
+
+### display_text
+
+This is a special type that allows the application packager to write some text
+that will be simply displayed. This is useful to provide more context.
+
+```toml
+[maybe.some.stuff.before.the_name]
+type = "display_text"
+ask.en = "the text in english"
+ask.fr = "the text in french"
+```
+
+And in javascript:
+
+```javascript
+{
+    "name": "the_name",
+    "type": "display_text",
+    "ask": {
+        "en": "the text in english",
+        "fr": "the text in french"
+    }
+},
+```

packaging_apps_config_panel.md

@@ -60,6 +60,11 @@ REALLY wants it but we really don't recommend it has it is very error prone and
 frustrating to write by hand) that will be located at the root of you
 application, next to the manifest.json/toml. It looks like this:
 
+<div class="alert alert-info">
+The options are written in **[YunoHost Arguments
+Format](#/packaging_apps_arguments_format)** like in `manifest.toml/json`
+</div>
+
 ```toml
 version = "0.1"  # version number, not used yet but important
 name = "name that will be displayed on the admin"