continue gen doc documentation

.drone.yml

@@ -16,8 +16,8 @@ steps:
 - name: pandoc
   image: pandoc/alpine:2.14
   commands:
-    - ls
-    - sh build-pandoc.sh latex > user-manual.tex
+    - sh build-pandoc.sh latex user > user-manual.tex
+    - sh build-pandoc.sh latex admin > user-manual.tex
   when:
     event: tag
 
@@ -25,6 +25,7 @@ steps:
   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
 
@@ -36,6 +37,7 @@ steps:
     base_url: https://gitea.champs-libres.be
     files:
       - user-manual.pdf
+      - admin-manual.pdf
     checksum:
       - sha512
     title: ${DRONE_COMMIT_REF}

.gitignore

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

README.md

@@ -1,5 +1,5 @@
-Manuel utilisateur Vendée
-=========================
+Manuels Vendée
+==============
 
 ## Compilation
 
@@ -11,7 +11,7 @@ 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

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,12 +1,11 @@
 #!/bin/sh
 
+set -e
+
 # enter the current directory
 cd "$(dirname $0)"
 export PANDOC_DIR=pandoc/cl
 
-export files="
-  src/parcours.md
-"
 
 if [ -z $1 ]; then
   export target=pdf
@@ -14,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"
@@ -26,17 +44,17 @@ export LATEX_ARGS="
 "
 
 
-if [ $target == "latex" ]; 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

@@ -36,7 +36,7 @@ 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 concerné dispose d'une adresse, il est possible de localiser le parcours auprès de cet usager.