continue gen doc documentation

Squashed commit of the following:

commit 314aa4b989
Author: Julien Fastré <julien.fastre@champs-libres.coop>
Date:   Mon Jul 26 21:29:34 2021 +0200

    restrict ci on tags

commit c39b0d98d9
Author: Julien Fastré <julien.fastre@champs-libres.coop>
Date:   Mon Jul 26 17:59:27 2021 +0200

    add explanation to README about dependencies [ci-skip]

commit b935e1ba68
Author: Julien Fastré <julien.fastre@champs-libres.coop>
Date:   Mon Jul 26 17:55:50 2021 +0200

    clone submodules

commit 8dbc9aa196
Author: Julien Fastré <julien.fastre@champs-libres.coop>
Date:   Mon Jul 26 17:52:23 2021 +0200

    fix drone ci

commit 61fb8a8f66
Author: Julien Fastré <julien.fastre@champs-libres.coop>
Date:   Mon Jul 26 15:34:35 2021 +0200

    first impl for drone

.drone.yml

@@ -0,0 +1,46 @@
+---
+kind: pipeline
+type: docker
+name: default
+
+steps:
+
+- name: submodules
+  image: alpine/git
+  commands:
+  - git submodule init
+  - git submodule update --recursive --remote
+  when:
+    event: tag
+
+- name: pandoc
+  image: pandoc/alpine:2.14
+  commands:
+    - sh build-pandoc.sh latex user > user-manual.tex
+    - sh build-pandoc.sh latex admin > user-manual.tex
+  when:
+    event: tag
+
+- name: build-latex
+  image: ghcr.io/xu-cheng/texlive-full:latest
+  commands:
+    - latexmk -pdf -file-line-error -halt-on-error -interaction=nonstopmode -xelatex user-manual.tex
+    - latexmk -pdf -file-line-error -halt-on-error -interaction=nonstopmode -xelatex latex-manual.tex
+  when:
+    event: tag
+
+- name: release
+  image: plugins/gitea-release
+  settings:
+    api_key:
+      from_secret: gitea_key
+    base_url: https://gitea.champs-libres.be
+    files:
+      - user-manual.pdf
+      - admin-manual.pdf
+    checksum:
+      - sha512
+    title: ${DRONE_COMMIT_REF}
+    prerelease: true
+  when:
+    event: tag

.gitignore

@@ -1,2 +1,2 @@
 build/*
-user-manual.pdf
+*-manual.pdf

README.md

@@ -1,5 +1,5 @@
-Manuel utilisateur Vendée
-=========================
+Manuels Vendée
+==============
 
 ## Compilation
 
@@ -11,10 +11,15 @@ Commande:
 docker-compose up
 ```
 
-Le fichier généré est `user-manual.pdf`
+Le fichier généré est `user-manual.pdf` et `admin-manual.pdf`
 
 
 ### Utilisateur
 
 L'utilisateur qui exécute la compilation est, par défaut, l'utilisateur ayant l'id `1000`.
 
+## Dépendances latex
+
+### Awesomebox
+
+Pour créer des "box": https://www.ctan.org/tex-archive/graphics/awesomebox

admin/generation-documents.md

@@ -0,0 +1,198 @@
+
+# Génération de documents
+
+## Syntaxe de génération d'un document
+
+## Principes liés au variables
+
+### Nommage de variables
+
+Les variables contiennent des informations importées d'objets présents dans le logiciel. Par objet, nous entendons, par exemple, un utilisateur (User), un usager (Person), etc…
+
+Ces objets comportent plusieurs champs. On accède à ces champs en concaténant les noms de la variable qui contient un objet, et le nom des champs de ces objets.
+
+Par exemple: le créateur d'un document est disponible sous la variable `creator`. Cette variable est un objet de type `User`. Cet objet contient ces trois champs ([la liste complète est disponible ci-dessous](#sec:gendoc-var-user)):
+
+* `username`;
+* `service`;
+* `email`;
+
+Alors, pour indiquer le nom du créateur, son email et son service, on préfixe la variable par `creator`, et on ajoute les noms des champs de l'objet `User`, en commençant par une majuscule pour ces champs. Exemple:
+
+```
+Pour joindre ${creatorUsername} (service: ${creatorService}),
+vous pouvez envoyer un courriel à l'adresse ${creatorEmail}.
+```
+
+Pour nommer les variables et les concaténer, nous utilisons la syntaxe camelcase [^camelcase], avec la première lettre en bas de casse (en minuscule).
+
+[^camelcase]: <https://fr.wikipedia.org/wiki/Camel_case>
+
+#### Application aux variable date
+
+Les dates sont disponibles dans deux formats:
+
+* le format "court", ou dd/mm/yyyy (par exemple, 15/06/1980, 18/08/2021, …). Ce format est accessible par le champ `short`;
+* le format "long": 15 juin 1980, 18 août 2021, … Ce format est accessible par le champ `long`;
+
+lorsqu'une date est disponible, il est donc possible d'avoir accès à son format en précisant sa chaine de caractère. Exemple avec la date de naissance de la personne:
+
+```
+personBirthdateShort=15/06/1980
+personBirthdateLong=15 juin 1980
+```
+
+### Cas où une variable peut être de deux natures différentes
+
+Certaines variables peuvent être de deux natures différentes, par exemple, soit une personne, soit un tiers. Dans ce cas, les variables qui sont de noms différents sont à l'état "vide". Par exemple, le champ "date de naissance" n'est pas disponible pour un tiers, dans ce cas, il est vide.
+
+Exemple, une liste des interlocuteurs principaux. Le premier est une personne:
+
+```
+text=Maxime Berger
+firstName=Maxime
+lastName=Berger
+birthDate=19/01/1996
+type=
+job=
+```
+
+Le second est un tiers:
+
+```
+text=Jean Couteau
+firstName=Jean
+lastName=Couteau
+birthDate=
+type=Médecin
+job=Assistant social
+```
+
+## Variables disponibles par document
+
+### Pour chaque document
+
+* `creator`: (User) le créateur;
+* `createdAt` (Date): la date de création;
+* `locate`: le lieu sélectionné par le créateur, au moment de la génération;
+
+### Document générés pour un parcours
+
+Le document hérite de toutes les variables disponibles pour chaque document, à laquelle vient s'ajouter la variable suivante et tout ses champs:
+
+* `course` (Parcours)
+
+Par ailleurs, les listes suivantes sont disponibles:
+
+* `coursePersons` (liste de Person): une liste des personnes du parcours
+* `courseRequestor` (liste de Person ou ThirdParty): le demandeur. Peut être vide.
+* `courseResources` (liste de Person ou ThirdParty): une liste des interlocuteurs privilégiés
+* `courseSocialIssues` (liste de SocialIssues): la liste des problématiques d'accompagnement
+
+### Document générés pour une action d'accompagnement
+
+Le document hérite de toutes les variables et listes disponibles pour les document "générés par un parcours". De plus, les variables suivantes s'ajoutent:
+
+* `work` (Action d'accompagnement), et tout ses sous-champs;
+
+Les listes suivantes sont disponibles:
+
+* `workGoals`: une liste d'objectifs, où chaque item contient deux variables:
+    * `goal: le libellé de l'objectif (vide pour les résultats sans objectif);
+    * `result: une concaténation de toutes les appellations des résultats, séparés par une virgule;
+* `workThirdParties` (liste de ThirdParty): une liste de tiers associés à l'action;
+* `workPersons`: une liste de personnes associées à l'action
+  
+### Document générés pour une évaluation
+
+Le document hérite des variables et listes disponibles pour les documents "Action d'accompagnement", auxquelles viennent s'ajouter la variable `evaluation`:
+
+* `evaluation`: Evaluation
+
+## Champs par objet
+
+### Date
+
+* `short` (texte): la date au format dd/mm/yyyy, vide si la date est absente;
+* `long` (texte): la date au format jour mois années: 15 août 1980, vide si al date est absente;
+
+### Person
+
+* `firstName` (texte)
+* `lastName` (texte)
+* `text` (texte): représentation du nom, prénom, et noms alternatifs (voir `PersonRender::renderString)`)
+* `birthdate` (Date)
+* `deathdate` (Date)
+* `gender` (texte): peut être masculin, féminin, ou <à compléter>
+* `maritalStatus` (texte): représentation textuelle de l'état civil;
+* `email` (texte): adresse email
+* `firstPhoneNumber` (texte): soit le numéro de mobile s'il existe, soit le numéro fixe s'il existe, sinon vide;
+* `fixPhoneNumber` (texte): le numéro de téléphone fixe;
+* `mobilePhoneNumber` (texte): le numéro de téléphone portable;
+* `nationality` (texte): nationalité
+* `placeOfBirth (texte): le lieu de naissance
+* `memo` (texte): le mémo
+* `numberOfChildren` (texte): le nombre d'enfants
+* `currentAddress` (Adresse): l'adresse actuelle
+
+### ThirdParty
+
+TODO avec Mathieu
+
+### Adresse
+
+* `text` (texte): une chaine de caractère représentant l'adresse complète;
+* `street` (texte): le nom de la rue (exemple: "RUE DES ÉGLANTIERS");
+* `streetNumber` (texte): le numéro de police;
+* `postcodeName` (texte): le nom de la localité ou ville;
+* `postcodeCode` (texte): le code postal;
+* `countryName` (texte): le nom du pays;
+* `countryCode` (texte): le code du pays;
+* `floor` (texte): l'étage;
+* `corridor` (texte): le couloir;
+* `flat` (texte): l'appartement;
+* `buildingName` (texte): le nom du bâtiment / résidence;
+* `distribution` (texte): service particulier de distribution;
+* `extra` (texte): champs extras
+
+### User { #sec:gendoc-var-user }
+
+* `username` (texte)
+* `email` (texte)
+* `service` (texte): service principal
+
+### Parcours
+
+* `id` (texte): l'identifiant du parcours
+* `startDate` (texte): la date de confirmation du parcours (vide si le parcours est à l'état brouillon);
+* `endDate` (texte): la date de fin du parcours (vide si le parcours n'est pas clotûré);
+* `end` (texte): la mention "clotûré" si le parcours est clotûré;
+* `status` (texte): contient la mention "En file active", "Archivé", ou est vide si le parcours n'a aucun de deux statuts;
+* `ref`: (User): le référent du parcours;
+* `location` (Adresse): l'adresse de localisation du parcours
+* `personLocation` (Person): l'utilisateur qui localise le parcours (s'il y en a un, peut être vide);
+* `emergency` (texte): la chaine "Urgent" si le parcours est urgent, chaine vide sinon;
+* `confidential` (texte): "Confidentiel" si le parcours est confidentiel, chaine vide sinon;
+* `origin` (texte): l'appellation de l'origine du parcours;
+* `closingMotive` (texte): l'appellation du motif de clotûre du parcours;
+
+### Action d'accompagnement
+
+* `id` (texte): l'identifiant de l'action;
+* `note` (texte): la note;
+* `createDate` (Date): la date de création de l'action;
+* `startDate` (Date): la date de début de l'action (vide si inexistant)
+* `endDate` (Date): la date de début de l'action (vide si inexistant)
+* `handlingThirdParty` (ThirdParty): le tiers traitant
+
+### Evaluation
+
+* `id` (texte): l'identifiant de l'évaluation;
+* `type` (texte): le libellé de l'évaluation;
+* `startDate` (Date): la date de début de l'évaluation;
+* `endDate` (Date) la date de fin de l'évaluation;
+* `maxDate` (Date): la date d'échéance de l'évaluation;
+* `comment` (texte): le commentaire de l'évaluation;
+* `createdBy` (User): le créateur de l'évaluation;
+* `createdAt` (Date): la date de création de l'évaluation;
+

admin/metadata.yaml

@@ -0,0 +1,10 @@
+---
+title: Manuel administrateur de Chill
+subtitle: Chill en Vendée
+lang: fr-BE
+toc: true
+
+
+header-includes: |
+    \usepackage{awesomebox}
+...

build-pandoc.sh

@@ -1,14 +1,11 @@
-#!/bin/bash
+#!/bin/sh
 
-echo "This script is for building pandoc natively"
+set -e
 
 # enter the current directory
 cd "$(dirname $0)"
 export PANDOC_DIR=pandoc/cl
 
-files=(
-  src/parcours.md
-)
 
 if [ -z $1 ]; then
   export target=pdf
@@ -16,9 +13,28 @@ else
   export target=$1
 fi
 
+if [ -z $2 ]; then
+  export kind=user
+else
+  export kind=$2
+fi
+
+if [ $kind = 'user' ]; then
+  export files="
+    $kind/parcours.md
+  "
+elif [ $kind = 'admin' ]; then
+  export files="
+    $kind/generation-documents.md
+  "
+else 
+  echo "kind '$kind' is not valid";
+  exit 1;
+fi
+
 export ARGS="
   --from markdown
-  --metadata-file ./metadata.yaml
+  --metadata-file ./$kind/metadata.yaml
   --lua-filter "${PANDOC_DIR}/format-link.lua"
 "
 export PDF_TEMPLATE="./pandoc/template/eisvogel.tex"
@@ -28,17 +44,17 @@ export LATEX_ARGS="
 "
 
 
-if [ $target == "debug" ]; then
+if [ $target = "latex" ]; then
   pandoc $ARGS $LATEX_ARGS \
     --to latex \
     $files;
-elif [ $target == "pdf" ]; then
+elif [ $target = "pdf" ]; then
   pandoc $ARGS $LATEX_ARGS \
     --to pdf \
     --pdf-engine xelatex \
-    -o ./user-manual.pdf \
+    -o "./$kind-manual.pdf" \
     $files
-elif [ $target == "html" ]; then
+elif [ $target = "html" ]; then
   # check target directory exists
   if [ ! -d "./build/html" ]; then
     echo "create build/html directory"

docker-compose.yaml

@@ -1,11 +1,21 @@
 version: "3"
 
 services:
-    texlive:
+    texlive.user:
         image: chill_user_manual_build
         build:
             context: docker/latex
-        command: ./build-pandoc.sh
+        command: ./build-pandoc.sh pdf user
+        # currently hardcoded, sorry
+        user: "1000"
+        volumes:
+            - .:/workdir
+        working_dir: /workdir
+    texlive.admin:
+        image: chill_user_manual_build
+        build:
+            context: docker/latex
+        command: ./build-pandoc.sh pdf admin
         # currently hardcoded, sorry
         user: "1000"
         volumes:

user/parcours.md

@@ -22,7 +22,7 @@ Chaque parcours **doit** être localisé.
 La localisation est réalisée par l'une ou l'autre manière:
 
 * soit en indiquant une adresse temporaire sur le parcours;
-* soit en renseignant un usager concerné ou un interlocuteur privilégié du parcours. Dans ce cas, l'adresse du domicile de cet usager sera utilisée pour localiser le parcours.
+* soit en renseignant un des usagers concerné par le parcours. Dans ce cas, l'adresse du domicile de cet usager sera utilisée pour localiser le parcours. S'il déménage, son adresse sera réutilisée dès son déménagement, de manière automatique.
 
 ::: {.vendee}
 
@@ -36,27 +36,23 @@ La localisation des parcours permet:
 
 :::
 
-### Localiser le parcours auprès d'un usager concerné ou d'un interlocuteur privilégié
+### Localiser le parcours auprès d'un usager concerné
 
-Dans le cas où un usager ou un interlocuteur privilégié[^usager-only] dispose d'une adresse, il est possible de localiser le parcours auprès de cet usager.
-
-[^usager-only]: Uniquement les usagers: les tiers ne sont pas concernés.
+Dans le cas où un usager concerné dispose d'une adresse, il est possible de localiser le parcours auprès de cet usager.
 
 Lorsqu'un parcours est localisé auprès d'un usager:
 
 * le parcours "suit" l'adresse de l'usager lorsqu'il déménage;
-* il n'est pas possible de dissocier du parcours l'usager concerné ou l'interlocuteur privilégié;
+* il n'est pas possible de dissocier l'usager concerné du parcours;
 
 Par ailleurs,
 
 * l'usager ne peut pas quitter le parcours, tant que le parcours est localisé auprès de lui;
 * l'usager ne peut pas quitter son ménage sans laisser d'adresse, tant qu'il localisé auprès d'au moins un parcours.
 
-
 ### Localisation temporaire
 
 Une adresse temporaire peut être attribuée à un parcours.
 
+Dans ce cas, cette localisation est associée au parcours, et ne sera pas automatiquement modifiée si un usager déménageait. Pour éviter cette situation, un message d'avertissement rappelle qu'il est préférable d'indiquer une réelle localisation pour le parcours.
 
-
-###