Schéma YAML de fiche "Event" et "Site" pour l'AMF

Sommaire :

Le format YAML

Présentation du format YAML

YAML est un format destiné à décrire une stricure de données de façon simple et lisible pour un utilisateur humain. Il permet de décrire des structures listes ou dictionnaires) éventuellement imbriquées d'éléments de type chaines, entiers, ...

Pour une présentation du format YAML voir :

Dans le cadre de l'AMF, un fichier YAML sera simplement constitué d'une listes d'éléments appelés évènement (type Event ou Site pour le site AMF) constitué des champs ayant le type String.

En principe, les valeurs de type string doivent être encadrées de doubles quotes (i.e ""). Mais celles-ci peuvent souvent être omises quand il n'y a pas d'ambiguïté.

Quelques erreurs YAML fréquentes

YAML est un format conçu pour représenter des structures de données (liste de dictionnaires dans notre cas) de façon à rester facile à lire un un être humain. Le données elle-mêmes peuvent être de type nombre entier, chaine de caractères ou date.

Pour l'AMF, tous les champs sont interprétés en chaine de caractères, même le nombres de participants ce qui permet d'écrire "43 + 2 SMF" au lieu de 45.

Les valeurs de type chaine de caractères devraient être encadrées de "double guillemets", mais YAML ce débrouille pas trop mal pour détecter automatiquement les chaines de caractères

Schéma YAML pour les fiches de type Event (évènements)

Description des champs YAML d'une fiche Event (évènements)

  • Un champ manquant peut-être omis, ou simplement laissé vide
  • Une ligne commençant ar # est un commentaire
date
Exemple : 20200404
Pour un week-end, la date indiquée est celle du premier jour.
idéalement cette date devrait être unique, mais il arrive que deux évènements différents aient la même date (exemple : exposition de 2020 annulée et remplacée par la séance de formation !).
C'est pour cette raision que le champ suivant eid a été créé.
eid
Exemple : 20201003_expo
Ce champ facultatif est l'identifiant unique de l'évènement.
Il est indispensable en interne, mais est généralement une copie automatique du champ date. Cependant certaines dates correspondent à deux évenements différents, par exemple l'expo du 03/10/2020 annulée qui a été remplacée par la séance de formation. Dans ce cas on peut ajouter manuellement ce champ aux deux évènements, par exemple "20201003_expo" et "20201003_formation", ou plus simplement "20201003a" et "20201003b".
Cette valeur sera également utilisée (à terme) dans les noms des fichiers rapports ou de récolte.
ce champs ne contient que deux caractères alphanumériques (sans accent) ou de underscore "_", donc jamais de tirets "-".
period
AM: Après-Midi
MA: MAtin
JN: Journée
WE: WeekEnd
J3, J4 : période de 3 ou 4 jours
rdv_time
heure du rendez-vous (exemple : 10h00)
type
SORTIE (valeur par défaut) : sortie champignon
EXPO : exposition annuelle
FORMATION : formation (typiquement la demi-journée de formation)
AG : Assemblée générale
title
Le titre repris de celui figurant dans les actualités.
Le titre est utilisé pour construire la page des actualités.
Mettre entre guillemets si il commence pas un chiffre
Même s'il est standardisé pour les sorties au même endroit, ce champ reste totalement personalisable pour une sortie donnée.
status
État particulier de cette activité.
Formé d'un mot clé prédéfini, d'un point-virgule et de la raison (laisser vide sit rien d'annormal !)
Mots clé possibles :
  • CANCELED (annulé)
  • HIDDEN (masqué dans les listes publiques) (PAS ENCORE UTILISÉ !)

Exemples :
status: CANCELED ; COVID19 + sécheresse
status: CANCELED ; reportée en septembre

site_name
Identifiant unique représentant exactement le lieu d'une sortie,
Il correspond exactement au champ sid d'une fiche site.
Ce nom est utilisé en interne par exemple pour générer les liens vers les listes par site.
Exemples : m3p_courances, rougeau_pav_royal, ftb_bois_rond, nanteau_route_pavee, vfm_8_routes
Il est donc indispensable de créer la fiche d'un nouveau site exploré dans le fichier yaml séparé amf_sites.yaml avant de créer une fiche eventassociée.
site_label
Nom affichable du lieu (en français accentué).
Il correspond exactement au champ titre d'une fiche site.
Ce label redondant sera probablement supprimé ultérieurement car il est déjà dans le fiche du site. Cependant, tant que les fichiers event sont vérifiés manuellement, ce champ est bien pratique pour le contrôle du fichier yaml.

Exemples :

ssite_label: Massif des 3 Pignons ; Croix St Jérôme
site_label: Villefermoy ; Pavé de Boulains
animators
Liste des encadrents de la sortie.
haque personne est séparé pour un point-virgule, le Nom et le prénon étant séparé par une virgule.
Ultérieurement ce champs permettra d'afficher facilement la liste des sorties gérées par chaque animateur.
Il est de la forme Nom1, Prénom1 ; Nom2, Prénom2 ; ...
Exemple : 
animators: Despoix, Annette ; Degouille, Bruno ; Diamantini, Maurice
with
Société amie co-participatrice
Exemple : 
with: SMF
nb_participants
Chaine de caractères distinguant AMF et SMF ou invités,
Pour l'instant n'est pas encore exploité (ni même renseigné, mais ça pourra se faire).
Exemple : 
nb_participants: 24 AMF + 2 SMF + 1 invité
recolte_file (N'EST PLUS UTILISÉ)
Nom du fichier de récolte s'il existe (peut être une chaine arbitraire)
Si ce champ vaut "NONE", on considère qu'il n'y a pas de récolte.
Cependant prochainement, ce fichier de récolte sera recherché automatiquement. Ce champ ne sera alors utile que si le fichier n'a pas pu être trouvé automatiquement.
Dans une second phase, ce fichier ne sera plus rechrché, mais regénéré dynamiquement à la volée si la bse de donnée est èà jour, sinon ce champ sera alors consulté.
Exemple : 
recolte_file: NONE
recolte_file: rougeau-2019sep.pdf
# la version automatique devra plutot être de la forme suivante :
recolte_file: recolte-20221001.php
recolte_file: recolte-20221001-vfm_8_routes.php
report_file (N'EST PLUS UTILISÉ)
Nom du fichier rapport (pdf).
Ce champ peut être un nom de fichier arbitraire : rapport_201910010_congres_smf.pdf.
Si ce champ vaut "NONE", on considère qu'il n'y a pas de rapport.
Si ce champ vaut "AUTO", le fichier sera recherché automatiquement sous la forme "rapport-20100416.pdf".
Si ce champ est vide (ou non renseigné) on utilise "NONE".
note
Champs libre pour ajouter n'importe quoi.
Pour créer du texte sur plusieurs lignes il faut :
  • mettre le caractère pipe (|) à la suite du mot note:
  • mettre les lignes suivantes en dessous en indentant de deux caractères supplémentaires

Exemple complet détaillé d'une fiche Event

- date: 20190616
  period: JN
  rdv_time: 10h00
  type:
  title: Sortie en forêt de Villefermoy au carrefour des 8 Routes
  status:
  site_name: vfm_8_routes
  site_label: Villefermoy ; 8 Routes
  animators: Cholet, Michèle ; Laignel, Gilbert ; Pillot, Jean
  with:
  nb_participants: 22
  note: |
    On peut ajouter une remaque sur plusieurs lignes à condition d'ajouter
    le caractère "|" (pipe ou barre verticale) après le motclé.

Prototype complet vide de fiche Event

- date:
  period:
  rdv_time:
  type:
  title:
  status:
  site_name:
  site_label:
  animators:
  with:
  nb_participants
  note:

Schéma YAML pour les fiches de type Site

Description des champs YAML d'une fiche Site

  • Un champ manquant peut-être omis, ou simplement laissé vide
  • Une ligne commençant ar # est un commentaire
sid
Chaine d'identifiant unique pour un site ,
Les sid est représenté par le champ site_name dans une fiche event,
Pas de majuscule ni de caractères spéciaux (seul "_" est autorisé),
Lors de la création d'un nouveau site, il faut pense qu'il pourra y avoir d'autres points de rendez-vous dans la même forêt. Par exemple il ne faut pas appeler un site rougeau mais plutot rougeau_pav_royal même s'il n'y a pas encore d'autres sorties dans cette forêt.
Exemples : 
sid:  vfm_8_routes
abbrev:  8_routes
type
Type de site (salle de réunion, lieu publique, sortie myco, ...).
Formé d'un mot clé prédéfini simple en majuscule
permettra de classer les sites selon leur fonction (sortie sur le terrain, réunion, site potentiel pas encore utilisé par l'AMF, ...)
Liste des mots clé possibles (par encore bien défini : dépendra de l'utilisation future) :
  • UNDEF : indéfini ou vide
  • SORTIE ou XXXX : sortie, myco, zone de prospection normal (trouver un autre nom ?)
  • MEETING : salle de réunion ou de formation
  • EXPO : lieu vaste utilisé pour une exposition
  • ZONE : zone peu précise, sans coordonnées GPS, décrivant une destination de week-end par exemple
  • GEOPOS : localisation GPS diverse

Exemples :
type: HIDDEN

status
Statut particulier de ce site.
Formé d'un mot clé prédéfini, d'un point-virgule et de la raison (laisser vide sit rien d'annormal !)
permettra de classer les sites selon lkeur fonction (sortie sur le terrain, réunion, site potentiel pas encore utilisé par l'AMF, ...)
Mots clé possibles :
  • UNDEF : indéfini ou vide : valeur standard
  • HIDDEN : masqué dans les listes publiques (site non AMF, ou site candidat potenciel)

Exemples :
status: HIDDEN

abbrev
Abréviation du sid ou du nom du site,
Permet de retrouver les anciens fichiers de récolte,
Peut-être utile pour retrouver les noms de colonnes dans les fichiers d'inventaire Excel.
Ce champs est provisoire et est appelé à être supprimé
Exemples : 
sid:  ftb_grands_feuillards
abbrev:  grands-feuillards

sid:  ftb_franchard_isatis
abbrev:  isatis

sid:  rougeau_bois_arqueil
abbrev:  rougeau-arqueil

sid:  rougeau_pav_royal
abbrev:  rougeau

sid:  exposition
abbrev:  expo
title
Chaine composée de deux parties avec le lieu principal et le parking.
Ces deux parties sont séparées par un point-virgule pour être facilement manipulées informatiquement.
Exemple : 
title:  Rougeau ; Pavillon Royal
rdv_label
nom du lieu de rendez-vous (parking, carrefour, ...)
Exemple : 
rdv_label:  Parking du Pavillon Royal
rdv_gps
Coordonnées gps (q)uatre chiffres après la virgule suffisent).
Exemple : 
rdv_gps:  48.4997N 2.9110E
rdv_gps:  48.4997N;2.9110E (ou bien)
access_desc
Description textuelle de l'accès.
Généralement sur plusieurs lignes
Exemple : 
access_desc : |
  Accès par la D346 de Melun vers Corbeil. A Nandy, prendre à gauche
  au 2ème feu (vers le lotissement) puis suivre à droite vers le
  Chemin des Merles. Parking à 1 km
access_file
Image du fichier d'accès ou du lieu (et parfois de la carte IGN du lieu)
Le fichier, s'il existe, sera supposé rangé dans un répertoire particulier
Exemple : 
map_file:  rougeau_pav_royal.png
map_file
Carte du site (généralement un plan ign)
Le fichier, s'il existe, sera supposé rangé dans un répertoire particulier
Pour l'AMF, ce fichier est généralement intégré dans l'image access_file
Exemple : 
map_file:  rougeau_pav_royal_ign.png
gpx_files
liste de fichiers de trace au format gpx.
laisser vide en abscence de fichier.
plusieurs fichiers gpx peuvent être indiqués de deux manières :
  • soit sur une seule ligne :
gpx_files:  [trace_1.gpx, trace_2.gpx]
  • soit sur plusieurs lignes
gpx_files:
  - trace_1.gpx
  - trace_2.gpx
memo
tout complément d'information utile (comme l'historique ou autre)

Exemple complet détaillé d'une fiche Site

- sid: rougeau_pav_royal
  title: Rougeau ; Pavillon Royal
  rdv_label: Parking du Pavillon Royal
  rdv_gps: 48.5752N 2.5467E
  access_desc : |
    Accès par la D346 de Melun vers Corbeil. A Nandy, prendre à gauche
    au 2ème feu (vers le lotissement) puis suivre à droite vers le
    Chemin des Merles. Parking à 1 km
  access_file: "Forêt de Rougeau.pdf"
  map_file: "rougeau_pav_royal.png"
  # gpx_files:  [trace_1.gpx, trace_2.gpx]
  gpx_files:
    - trace_1.gpx
    - trace_2.gpx
  memo:

Prototype vide de fiche Site

- sid:
  title:
  rdv_label:
  access_desc:
  access_file:
  map_file:
  gpx_files:
  memo: