doc (apps): fix the apps documentation:

The page was a messy reference, with several fields missing or incomplete. It is now
completed and easier to read.

doc/apps.rst

@@ -1,21 +1,27 @@
 .. _libervia-app-config:
 
-=================================
+Libervia Apps
-Libervia App Configuration (YAML)
+=============
-=================================
 
-The Libervia application uses a YAML configuration file to define various aspects of the
+Libervia Apps are third party software, embedded and integrated in Libervia, usually as
-application's behavior, environment, and settings.
+containers (Podman, Docker).
 
-The file will be parsed by `PyYAML`_ which is a full-featured YAML implementation. Check
+Each app is defined by a YAML configuration file, which describes how to run it and which
-its documentation for details.
+settings are exposed. App files are named ``libervia_app_<name>.yaml`` and are discovered
+from the app manager plugin directories.
 
-Below is the documentation explaining the structure and functionality of each field in the
+Below is the documentation of each field of the YAML file.
-YAML file.
 
-=================
+-----------------
 Root-Level Fields
-=================
+-----------------
+
+- ``name``: Human readable name of the application. The file name (without the
+  ``libervia_app_`` prefix) is used when not specified.
+
+- ``single_instance``: When ``True`` (default), only one instance of the application can
+  be started at a time, and its data are kept between restarts. When ``False``, each start
+  creates a new temporary instance directory, removed when the backend is unloaded.
 
 - ``type``: Specifies the type of the application. See :ref:`libervia-app_type`.
 
@@ -27,16 +33,18 @@ Root-Level Fields
 
 - ``expose``: Specifies configurations exposed to frontends or administrators. See :ref:`libervia-app_expose`.
 
-==================
+------------------
 Detailed Sections
-===================
+------------------
 
 .. _libervia-app_type:
 
 type
 ^^^^
 
-Currently, the only supported type is ``docker-compose``.
+Currently, the only supported type is ``docker-compose``. The container engine is chosen
+with the ``engine`` plugin setting: ``auto`` (default, Podman is tried first), ``docker``
+or ``podman``.
 
 .. _libervia-app_prepare:
 
@@ -46,7 +54,7 @@ prepare
 The ``prepare`` section specifies things like git repositories to be cloned before running the application.
 
 Example
--------
+~~~~~~~
 Cloning the repository at `https://example.org/some/repository.git` to prepare the app:
 
 .. code-block:: yaml
@@ -65,7 +73,7 @@ The YAML key is the name of the file to be created, and the content specified wi
 populate that file.
 
 Example
--------
+~~~~~~~
 Creating a file named `settings-override.py` with the content `USE_X_FORWARDED_HOST = True`:
 
 .. code-block:: yaml
@@ -86,7 +94,7 @@ creates a ``docker-compose.override.yml`` file that will be merged with the defa
 <https://docs.docker.com/compose/reference/#specifying-multiple-compose-files>`_.
 
 Example
--------
+~~~~~~~
 Overriding the `ports` for the `example_app` service to expose port `8080`:
 
 .. code-block:: yaml
@@ -102,9 +110,31 @@ Overriding the `ports` for the `example_app` service to expose port `8080`:
 Exposing Data
 ^^^^^^^^^^^^^
 
-The `expose` section specifies the configurations that are exposed to users or frontends.
+The ``expose`` section specifies the data exposed to users, frontends or administrators.
-See :ref:`libervia-app_param` for a reference of some exposed data. Ports and generated
+
-passwords are exposed in dicts, respectively at the ``ports`` and  ``passwords`` key.
+The following keys are used by the Web frontend:
+
+url_prefix
+    The internal URL where the app will be served.
+web_label
+    Label which will be used in the Web frontend.
+web_url_path
+    Public facing URL path which will be used in the Web frontend to access the app.
+web_external
+    If True, the Web frontend will open the app in a separated page instead of embedding
+    it.
+front_url
+    Whole URL to access the app, useful when it has its own domain or subdomain. The
+    ``https`` scheme is added if not specified.
+
+Ports and generated passwords are exposed in dicts, respectively at the ``ports`` and
+``passwords`` keys. Each entry of ``ports`` maps a name to the compose ``service`` and
+``private`` (container) port, it is resolved to the exposed ``host:port`` when the app is
+running. Each entry of ``passwords`` maps a name to the list of keys leading to the value
+to expose in the application data.
+
+``url_prefix`` and ``front_url`` can also be specified as a list of keys leading to the
+value in the application data.
 
 .. _libervia-app_yaml-tags:
 
@@ -116,32 +146,49 @@ The following YAML tags can be used in the Libervia App configuration file:
 .. _libervia-app_conf:
 
 !libervia_conf
-++++++++++++++
+^^^^^^^^^^^^^^
 
-Get a value from Libervia configuration. A list is expected with either:
+Get a value from the Libervia configuration. It takes a list of 1 to 4 items:
 
-- `name` of a config parameter
+- ``[NAME]``: the ``NAME`` option of the ``[common]`` section
-- `section` and `name` of a config parameter
+- ``[SECTION, NAME]``: the ``NAME`` option of the section named ``SECTION``
-- `section`, `name`, and `default` value of a config parameter
+- ``[SECTION, NAME, DEFAULT]``: use ``DEFAULT`` if the option is not set
-- `section`, `name`, `default` value, and `filter` (either `first` or `not`)
+- ``[SECTION, NAME, DEFAULT, FILTER]``: apply a filter to the value (see below)
 
-Filter options:
+The ``application.<name>`` section refers to the configuration section of the
+``<name>`` application (e.g. ``application.peertube``).
 
-- `first`: get the first item of the value
+Available filters:
-- `not`: get the opposite value (to be used with booleans)
 
-Example
+- ``first``: get the first item of the value
--------
+- ``not``: get the opposite value (to be used with booleans)
-Getting a value from Libervia configuration:
+
+Examples
+~~~~~~~~
+Getting a value from an application configuration section:
 
 .. code-block:: yaml
 
-  !libervia_conf [section, name, default]
+  !libervia_conf [application.peertube, hostname]
+
+Getting the SMTP server from the ``[email]`` section (an empty default is
+used when the option is not set):
+
+.. code-block:: yaml
+
+  !libervia_conf [email, server, ""]
+
+Getting the first email of the ``[common]`` section admin list (using the
+``first`` filter):
+
+.. code-block:: yaml
+
+  !libervia_conf [common, email_admins_list, "", first]
 
 .. _libervia-app_generate_pwd:
 
 !libervia_generate_pwd
-+++++++++++++++++++++
+^^^^^^^^^^^^^^^^^^^^^^
 
 Generate a password and store it in persistent data. If the password has already been generated previously, it is reused.
 
@@ -152,7 +199,7 @@ Arguments:
 - `size` (int): Size of the password to generate. Default to 30
 
 Example
--------
+~~~~~~~
 Generating a password named ``some_password`` with a size of 32 characters:
 
 .. code-block:: yaml
@@ -162,35 +209,23 @@ Generating a password named ``some_password`` with a size of 32 characters:
 .. _libervia-app_param:
 
 !libervia_param
-++++++++++++++
+^^^^^^^^^^^^^^^
 
 Get a parameter specified when starting the application. The value can be either the name
 of the parameter to get, or a list as `[name, default_value]`.
 
-
-
 Available parameters:
 
 url_prefix
-    The internal URL where the app will be served.
+    The internal URL where the app will be served, it is given by the Web frontend.
-web_label
+front_url_path
-    Label which will be used in Web frontend.
+    The URL path which will be used in the Web frontend to access the app.
-web_url_path
-    Public facing URL path which will be used in the web frontend to access the app.
-web_external
-    If True, the web frontend will open the app in a separated page instead of embedding
-    it.
-front_url
-    Whole URL to access the app. It is specified when the app has its own domain or
-    subdomain.
 
 Example
--------
+~~~~~~~
 Getting a parameter:
 
 .. code-block:: yaml
 
   !libervia_param [url_prefix, /some_app]
 
-.. _PyYAML: https://pyyaml.org/
-