Improve ansible role documentation generation | refs #38626

roles/base/README.md

+# Base
+## Description
+
+The base group is a meta-group used only to group together the various dependencies required by UbiCast solutions.  
+ 
+This group is only meant to be used as a meta group (see for instance meta groups section in the [standard example inventory](../../inventories/example/std/hosts) or [HA example inventory](../../inventories/example/ha/hosts)).  
+You should also look at the metagroups of base to fill out the variables in your inventory: [init](../init/README.md), [sysconfig](../sysconfig/README.md), [sysuser](../sysuser/README.md), [postfix](../postfix/README.md), [ferm-install](../ferm-install/README.md), [ferm-configure](../ferm-configure/README.md), [fail2ban](../fail2ban/README.md).

roles/celerity/README.md

 # Celerity
+## Description
 
 The celerity group is used to configure the hosts that balance the transcoding tasks.  
  * In a standard UbiCast case, the host is the same as the mediaserver.

roles/fail2ban/README.md

 # Fail2ban
+## Description
+
+Used by the "base" metagroup to provide and configure ban capabilities for various services
 
 ## Role Variables
 

roles/ferm-configure/README.md

 # Ferm-configure
+## Description
+
+Used by the "base" metagroup to configure the firewall solution
 
 ## Role Variables
 

roles/ferm-install/README.md

 # Ferm-install
+## Description
+
+Used by the "base" metagroup to install the firewall solution
 
 ## Role Variables
 

roles/init/README.md

+# Init
+## Description
+
+Used by the "base" metagroup to provide basic utilities and initialise a mandatory proxy if necessary

roles/live/README.md

 # Live
+## Description
 
 The live group is used to configure all hosts that will process lives streams.  
  * In a standard Ubicast case, the host is the same as the mediaserver.

roles/mediacache/README.md

 # Mediacache
+## Description
 
 The cache group is used to configure all hosts that will server as a proxy cache of live and/or vod.
 
@@ -11,7 +12,7 @@ Available variables are listed below, along with the descriptions and the defaul
 cache_domain: "cache.example.com"
 ```
 
-`nudgis_front_domain`: URL of Nudgis Front cluster (Optional)
+`nudgis_front_domain`: URL of Nudgis Front cluster
 ```
 nudgis_front_domain: "nudgis.example.com"
 ```

roles/mediaimport/README.md

+# Mediaimport
+## Description
+
+The cache group is used to configure all hosts that allow video to be added to the Nudgis platform via an upload (sftp, ftp(s)).

roles/mediaserver/README.md

 # Mediaserver
+## Description
 
 The mediaserver group is used to configure all hosts with the UbiCast platform to handle and to broadcast media.  
  * In a standard Ubicast case, the host is the same as other component (mirismanager, etc.)
@@ -18,7 +19,7 @@ nudgis_front_email_from: "noreply@{{ nudgis_front_domain }}"
 nudgis_front_system_user: "msuser"
 ```
 
-`nudgis_front_domain`: Defines the default deployed Nudgis portal domain (will be the URL of the portal when adding the HTTP(S) prefix) (Optional)
+`nudgis_front_domain`: Defines the default deployed Nudgis portal domain (will be the URL of the portal when adding the HTTP(S) prefix)
 ```
 nudgis_front_domain: "nudgis.example.com"
 ```

roles/mediavault/README.md

 # Mediavault
+## Description
 
 The mediaserver group is used to configure all hosts with the UbiCast backup solution 
 

roles/mediaworker/README.md

 # Mediaworker
+## Description
 
 The mediaorker group is used to configure the hosts treat the transcoding tasks.  
  * In a standard UbiCast case, the host is a dedicated server

roles/mirismanager/README.md

 # Mirismanager
+## Description
 
 The mediaserver group is used to configure all hosts with the UbiCast platform to control and manage video recorders.  
  * In a standard Ubicast case, the host is the same as mediaserver
@@ -8,7 +9,7 @@ The mediaserver group is used to configure all hosts with the UbiCast platform t
 
 Available variables are listed below, along with the descriptions and the default values.
 
-`manager_domain`: Defines the default domain for the Nudgis Manager (Optional)
+`manager_domain`: Defines the default domain for the Nudgis Manager
 ```
 manager_domain: "manager.example.com"
 ```

roles/monitor/msmonitor/README.md

 # Msmonitor
+## Description
 
 The msmonitor group is used to configure all hosts to allow to access to monitoring data through a secure web interface.  
- * In a standard and HA Ubicast case, the host(s) is(are) the same as mediaserver
+ * In a standard and HA Ubicast case, the host(s) is(are) the same as mediaserver  
+ 
+This group is only meant to be used as a meta group (see for instance meta groups section in the [standard example inventory](../../inventories/example/std/hosts) or [HA example inventory](../../inventories/example/ha/hosts)).
 
 ## Role Variables
 
 Available variables are listed below, along with the descriptions and the default values.
 
-`monitor_domain`: Defines the default domain for monitor (Optional)
+`monitor_domain`: Defines the default domain for monitor
 ```
 monitor_domain: "monitor.example.com"
 ```

roles/monitor/munin_node/README.md

 # Munin_node
+## Description
 
 The munin_node group is used to configure all hosts to send monitoring data back to the monitoring server (munin_server group).  
    * In a standard and HA Ubicast case, the hosts are all those that compose the UbiCast platform
 
+This group is only meant to be used as a meta group (see for instance meta groups section in the [standard example inventory](../../inventories/example/std/hosts) or [HA example inventory](../../inventories/example/ha/hosts)).
+
 ## Role Variables
 
 Available variables are listed below, along with the descriptions and the default values.

roles/monitor/munin_server/README.md

 # Munin_server
+## Description
 
 The munin_server group is used to configure all hosts for publishing monitoring data  
- * In a standard and HA Ubicast case, the host(s) is(are) the same as mediaserver
+ * In a standard and HA Ubicast case, the host(s) is(are) the same as mediaserver  
+ 
+This group is only meant to be used as a meta group (see for instance meta groups section in the [standard example inventory](../../inventories/example/std/hosts) or [HA example inventory](../../inventories/example/ha/hosts)).
 
 ## Role Variables
 

roles/postfix/README.md

 # Postfix
+## Description
 
-The postfix group is used to configure all hosts to send email.  
+Used by the "base" metagroup to provide emailing capabilities
 
 ## Role Variables
 

roles/postgres/README.md

 # Postgres
+## Description
 
 The postgres group is used to configure the host with a postgresql database.  
- The database can be deployed in standard mode or HA mode (3 servers, 2 configured in active/passive with an automatic switchover and witness).
- The group will determine whether to deploy standard or HA depending on the number of servers in the group (>=2 for the HA case).
+The database can be deployed in standard mode or HA mode (3 servers, 2 configured in active/passive with an automatic switchover and witness).
+The group will determine whether to deploy standard or HA depending on the number of servers in the group (>=2 for the HA case).
 
 ## Role Variables
 

roles/sysconfig/README.md

 # Sysconfig
+## Description
+
+Used by the "base" metagroup to provide core system utilities and their configuration
 
 ## Role Variables
 

roles/sysuser/README.md

 # Sysuser
+## Description
+
+Used by the "base" metagroup to setup the system users
 
 ## Role Variables