add CI workflow to build and push MkDocs Docker image

Reviewed-on: #10

.gitea/workflows/build-and-push-mkdocs-docker-image.yml

@@ -0,0 +1,94 @@
+name: Build and Push MkDocs Docker Image
+
+on:
+    push:
+        branches:
+            - main
+            - master
+        paths:
+            - 'Dockerfile'
+            - 'user/**'
+            - 'admin/**'
+            - '.gitea/workflows/**'
+    workflow_dispatch:
+
+jobs:
+    build-and-push:
+        runs-on: cth-ubuntu-latest
+
+        env:
+            REGISTRY: ${{ vars.REGISTRY }}
+            IMAGE: ${{ vars.IMAGE }}
+            IMAGE_NAME: ${{ env.REGISTRY }}/${{ IMAGE }}:${{ github.sha }}
+            KUBE_CA: ${{ vars.KUBE_CA }}
+            KUBE_SERVER: ${{ vars.KUBE_SERVER }}
+            REGISTRY_USERNAME: ${{ vars.REGISTRY_USERNAME }}
+            NAMESPACE: ${{ vars.NAMESPACE }}
+            DEPLOYMENT_NAME: ${{ vars.DEPLOYMENT_NAME }}
+            CONTAINER: ${{ vars.CONTAINER }}
+
+        steps:
+            -   name: Checkout code
+                uses: https://github.com/actions/checkout@v4
+
+            -   name: Set up Docker Buildx
+                uses: https://github.com/docker/setup-buildx-action@v3
+
+            -   name: Log in to Docker registry
+                uses: https://github.com/docker/login-action@v3
+                with:
+                    registry: ${{ env.REGISTRY }}
+                    username: ${{ env.REGISTRY_USERNAME }}
+                    password: ${{ secrets.REGISTRY_PASSWORD }}
+
+            -   name: Build and push
+                id: build-push
+                uses: https://github.com/docker/build-push-action@v5
+                with:
+                    context: .
+                    file: documentation.Dockerfile
+                    push: true
+                    tags: '${{ env.IMAGE_NAME }}'
+
+            -   name: Install kubectl
+                run: |
+                    curl -LO "https://dl.k8s.io/release/v1.31.0/bin/linux/amd64/kubectl"
+                    chmod +x ./kubectl
+                    sudo mv ./kubectl /usr/local/bin/kubectl
+
+            -   name: Set up kubeconfig
+                env:
+                    KUBE_SERVER: ${{ env.KUBE_SERVER }}      # e.g. https://<API_ENDPOINT>
+                    KUBE_CA: ${{ env.KUBE_CA }}              # base64 encoded, or fetched via kubectl config view
+                    KUBE_TOKEN: ${{ secrets.KUBE_TOKEN }}        # Token generated via 'kubectl create token'
+                run: |
+                    mkdir -p ~/.kube
+                    cat <<EOF > ~/.kube/config
+                    apiVersion: v1
+                    kind: Config
+                    clusters:
+                      - name: default-cluster
+                        cluster:
+                          server: "$KUBE_SERVER"
+                          certificate-authority-data: "$KUBE_CA"
+                    contexts:
+                      - name: default-context
+                        context:
+                          cluster: default-cluster
+                          user: gitea-actions
+                    current-context: default-context
+                    users:
+                      - name: gitea-actions
+                        user:
+                          token: "$KUBE_TOKEN"
+                    EOF
+
+            -   name: Patch Deployment Image
+                env:
+                    NAMESPACE: ${{ env.NAMESPACE }}
+                    DEPLOYMENT: ${{ env.DEPLOYMENT_NAME }}
+                    CONTAINER: ${{ env.CONTAINER }}
+                run: |
+                    echo "deploy new tag: $TAG_IMAGE"
+                    env
+                    kubectl -n ${NAMESPACE} set image deployment/${DEPLOYMENT} ${CONTAINER}=${IMAGE_NAME}

.gitignore

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

.idea/.gitignore

@@ -0,0 +1,8 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

.idea/manuals.iml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="Python 3.10 (manuals)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="TemplatesService">
+    <option name="TEMPLATE_FOLDERS">
+      <list>
+        <option value="$MODULE_DIR$/pandoc/cl/templates" />
+      </list>
+    </option>
+  </component>
+</module>

.idea/misc.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="Python 3.10 (manuals)" />
+  </component>
+</project>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/manuals.iml" filepath="$PROJECT_DIR$/.idea/manuals.iml" />
+    </modules>
+  </component>
+</project>

.idea/vcs.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+    <mapping directory="$PROJECT_DIR$/pandoc/cl" vcs="Git" />
+    <mapping directory="$PROJECT_DIR$/pandoc/template" vcs="Git" />
+  </component>
+</project>

Dockerfile

@@ -0,0 +1,23 @@
+# -------- Stage 1: Build the documentation using mkdocs --------
+FROM python:3.13-slim AS builder
+
+WORKDIR /build
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY user/ user/
+COPY admin/ admin/
+
+RUN ls
+RUN cd user && mkdocs build --clean && cd ..
+RUN cd admin && mkdocs build --clean && cd ..
+
+# -------- Stage 2: Serve the built documentation with nginx --------
+FROM nginx:alpine
+
+# Copy the built site from the builder stage
+COPY --from=builder /build/admin/site /usr/share/nginx/html/admin
+COPY --from=builder /build/user/site /usr/share/nginx/html/user
+

admin/.gitignore

@@ -0,0 +1 @@
+site/*

admin/docs/generation-documents.md

@@ -1,4 +1,3 @@
-
 # Génération de documents
 
 L'administrateur fonctionnel prépare la génération des documents.
@@ -139,9 +138,9 @@ Les options disponibles dépendent du contexte.
 
 Par exemple, pour un courrier généré dans un contexte "parcours", l'utilisateur pourra choisir un usager du parcours pour un courrier; l'administrateur indiquera qu'il s'agira du "destinataire" du courrier. Tandis que pour un formulaire officiel, l'administrateur configurera un "demandeur" et "co-demandeur", et ce sont ces libellés qui s'afficheront.
 
-## Variables par contexte
+## Variables par contexte 
 
-### Pour tous les contextes { #sec:gendoc:champs-documents }
+### Pour tous les contextes { #sec:gendoc-champs-documents }
 
 #### Variables
 
@@ -159,6 +158,7 @@ Les administrateurs fonctionnels peuvent activer les paramètres suivants:
 * un champ "usager 1", qui permet ensuite à l'utilisateur de choisir un usager parmi ceux concernés par le parcours, les interlocuteurs privilégiés qui sont des usagers (à l'exclusion des tiers), et les personnes ressources associées à un usager concerné du parcours (à l'exclusion des ressources tiers et "texte libre");
 * un champ "usager 2", qui permet aux utilisateurs de choisir un deuxième usager parmis ceux concernés par le parcours, les interlocuteurs privilégiés qui sont des usagers (à l'exclusion des tiers), et les personnes ressources associées à un usager concerné du parcours (à l'exclusion des ressources tiers et "texte libre");
 * un champ "usager principal du parcours", qui permet, cette fois, de choisir parmi les usagers concernés par le parcours, les interlocuteurs privilégiés qui sont des usagers (à l'exclusion des tiers), et les personnes ressources associées à un usager concerné du parcours (à l'exclusion des ressources tiers et "texte libre");
+* un champ "tiers", qui permet de choisir un tiers parmi les tiers "personnes ressources" du parcours, ou le demandeur du parcours (s'il s'agit d'un tiers);
 
 #### Variables
 
@@ -168,6 +168,7 @@ Le document présente:
 * si `usager principal du parcours` est coché, une variable `mainPerson`, de type `Person`, avec les variants `relations`, `household` (ménage) et `budget`;
 * si `usager 1` est coché, une variable `person1`, de type Person, avec les variants `relations`, `household` (ménage) et `budget`;
 * si `usager 2` est coché, une variable `person2`, de type Person, avec les variants `relations`, `household` (ménage) et `budget`;
+* une variable `thirdParty`, de type `ThirdParty`, uniquement si l'administrateur fonctionnel l'a configuré.
 
 ### Document générés pour un parcours, contexte "liste des activités"
 
@@ -187,6 +188,7 @@ Le document présente:
 * si `usager principal du parcours` est coché, une variable `mainPerson`, de type `Person`, avec les variants `relations`, `household` (ménage) et `budget`;
 * si `usager 1` est coché, une variable `person1`, de type Person, avec les variants `relations`, `household` (ménage) et `budget`;
 * si `usager 2` est coché, une variable `person2`, de type Person, avec les variants `relations`, `household` (ménage) et `budget`;
+* une variable `thirdParty`, de type `ThirdParty`, uniquement si l'administrateur fonctionnel l'a configuré.
 
 ### Document générés pour un échange
 
@@ -204,7 +206,8 @@ Il est possible également d'injecter des dossiers d'usagers, parmi ceux associ
 
 ### Documents générés dans le dossier d'une personne: contexte "personne basique"
 
-* une variable `person`, de type `Person`, avec les variants `relations`, `household` (ménage) et `budget`.
+* une variable `person`, de type `Person`, avec les variants `relations`, `household` (ménage) et `budget`;
+* une variable `thirdParty`, de type `ThirdParty`, uniquement si l'administrateur fonctionnel l'a configuré.
 
 ### Documents générés dans le dossier d'une personne: contexte "personne avec un tiers"
 
@@ -466,6 +469,12 @@ Seul le champ `comment` est donc disponible.
 * `id` (texte): identifiant
 * `title` (texte): le titre du résultat
 
+### GenderEntity (Genre)
+
+* `label` (texte): label du genre;
+* `id` (int): identifiant (utile pour des comparaisons);
+* `genderTranslation` (texte): utilisation grammaticale;
+
 ### Household (Ménage)
 
 
@@ -534,7 +543,7 @@ La composition du ménage entre deux dates. Cette entité associe une `Household
 * `birthdate` (Date)
 * `age`: (int) age de la personne;
 * `deathdate` (Date)
-* `gender` (texte): genre (texte traduit);
+* `genderEntity` (GenderEntity): Genre;
 * `maritalStatus` (texte): représentation textuelle de l'état civil;
 * `maritalStatusDate` (Date): date à la quelle le statut de l'état civil a été mis à jour;
 * `maritalStatusComment` (Comment): Commentaire sur l'état civil (avec la date de la dernière mise à jour)
@@ -549,6 +558,9 @@ La composition du ménage entre deux dates. Cette entité associe une `Household
 * `address` (Adresse): l'adresse actuelle
 * `resources` (PersonResource): les personnes ressources, ajoutées depuis le dossier de l'usager.
 
+
+**Note**: La clé `gender` est dépréciée. Merci d'utiliser `GenderEntity`.
+
 #### variant `household`
 
 * `household` (Household): le ménage actuel de l'usager;

admin/docs/index.md

@@ -0,0 +1,3 @@
+# Documentation administrateur
+
+En construction.

admin/mkdocs.yml

@@ -0,0 +1,43 @@
+---
+site_name: "Manuel admnistrateur Chill"
+site_url: https://manuel.chill.social/admin
+repo_url: https://gitea.champs-libres.be/Chill-project/manuals
+repo_name: Chill-project/manuals
+theme:
+    name: material
+    features:
+        - content.code.copy
+        - content.code.select
+        - content.code.annotate
+nav:
+    -   Accueil: index.md
+    -   Génération de document: generation-documents.md
+markdown_extensions:
+    - markdown_include.include
+    # code layout
+    - pymdownx.highlight:
+          anchor_linenums: true
+          line_spans: __span
+          pygments_lang_class: true
+          use_pygments: true
+          linenums: true
+    - pymdownx.inlinehilite
+    - pymdownx.snippets
+    - pymdownx.superfences
+    # admonition
+    - admonition
+    - pymdownx.details
+    - pymdownx.superfences
+    # use emojis
+    - attr_list
+    - pymdownx.emoji:
+        emoji_index: !!python/name:material.extensions.emoji.twemoji
+        emoji_generator: !!python/name:material.extensions.emoji.to_svg
+    # footnotes
+    - footnotes
+    # https://squidfunk.github.io/mkdocs-material/reference/formatting/?h=key#adding-keyboard-keys
+    - pymdownx.critic
+    - pymdownx.caret
+    - pymdownx.keys
+    - pymdownx.mark
+    - pymdownx.tilde

build-pandoc.sh

@@ -4,7 +4,8 @@ set -e
 
 # enter the current directory
 cd "$(dirname $0)"
-export PANDOC_DIR="/pandoc/cl"
+export PANDOC_DIR="$(pwd)/pandoc/cl"
+export OUTPUT_DIR="$(pwd)"
 
 
 if [ -z $1 ]; then
@@ -59,23 +60,22 @@ else
   exit 1;
 fi
 
-cd $kind
+export PDF_TEMPLATE="$(pwd)/eisvogel.latex"
+
+cd $kind/docs
 
 export ARGS="
   --from markdown
   --number-sections
   --resource-path ./.
   --metadata-file ./metadata.yaml
-  `#--lua-filter "../${PANDOC_DIR}/format-link.lua`
 "
-export PDF_TEMPLATE="./../pandoc/template/eisvogel.tex"
 export LATEX_ARGS="
   --metadata=footer-left:$(date +%d-%m-%Y)
-  --template "${PDF_TEMPLATE}"
-  --lua-filter "../${PANDOC_DIR}/boxes.lua"
+  --template ${PDF_TEMPLATE}
+  --lua-filter "${PANDOC_DIR}/boxes.lua"
 "
 
-
 if [ $target = "latex" ]; then
   pandoc $ARGS $LATEX_ARGS \
     --to latex \
@@ -84,18 +84,7 @@ elif [ $target = "pdf" ]; then
   pandoc $ARGS $LATEX_ARGS \
     --to pdf \
     --pdf-engine xelatex \
-    -o "./../$kind-manual.pdf" \
+    -o "${OUTPUT_DIR}/$kind-manual.pdf" \
     $files
-elif [ $target = "html" ]; then
-  # check target directory exists
-  if [ ! -d "./../build/html" ]; then
-    echo "create build/html directory"
-    mkdir -p "./../build/html"
-  fi
-
-  pandoc $ARGS \
-   --to html \
-   -o ./../build/html/index.html \
-  $files
 fi
 

requirements.txt

@@ -0,0 +1,3 @@
+mkdocs
+markdown-include
+mkdocs-material

user/.gitignore

@@ -0,0 +1,2 @@
+site/*
+

user/docs/exports_accompanying_period.md

@@ -209,8 +209,11 @@ Ce filtre permet d'indiquer deux dates qui forment une période de recherche, ai
 
 Filtre les parcours qui avaient un des statuts sélectionné pendant la période de recherche. 
 
+Note: comme un parcours peut avoir différents statuts au cours du temps, le présent filtre tiendra compte des parcours qui ont eu ce statut au moins un jour dans la période indiquée, même si ce statut a été changé pendant la période.
+
 Pour les différentes statuts, voir la section correspondante: [statuts du parcours](#sec:parcours-statut).
 
+
 #### Filtrer les parcours par type d'échange
 
 <!-- PHPFILE: src/Bundle/ChillActivityBundle/Export/Filter/ACPFilters/ActivityTypeFilter.php -->
@@ -350,7 +353,7 @@ Groupe les parcours par localisation administrative.
 
 Groupe les parcours par motifs de clôture.
 
-Lorsqu'un parcours ne comporte pas de motif de clôture (parce qu'il est toujours ouvert), le regroupement est repris sous une ligne sans contenu.
+Lorsqu'un parcours ne comporte pas de motif de clôture (parce qu'il est toujours ouvert, ou qu'il a été ré-ouvert après une clôture), le regroupement est repris sous une ligne sans contenu.
 
 #### Grouper les parcours par métier de l'intervenant
 

user/docs/exports_activity.md

@@ -76,6 +76,14 @@ Le filtre prend en compte tous les utilisateurs ajoutés dans les "parties conce
 
 L'échange est pris en compte dès qu'un utilisateur dans les "parties concernées" est associé à l'un des métiers demandés.
 
+#### Filtrer les échanges par métier du créateur de l'échange
+
+<!-- PHPFILE: src/Bundle/ChillActivityBundle/Export/Filter/CreatorJobFilter.php -->
+
+Filtre les échanges par métier du créateur de l'échange.
+
+Le métier doit être associé à l'utilisateur à la date de l'échange.
+
 #### Filtrer les échanges par problématique liée
 
 <!-- PHPFILE: src/Bundle/ChillActivityBundle/Export/Filter/ACPFilters/BySocialIssueFilter.php-->
@@ -207,6 +215,14 @@ Le métier pris en compte est celui associé à l'utilisateur à la date de l'é
 
 **Relation un-à-plusieurs**: lorsque plusieurs utilisateurs participent à l'échange, l'échange est comptabilisé une seule fois par métier de chaque utilisateur. Si plusieurs utilisateurs participant comportent le même métier, l'échange n'est donc comptabilisé qu'une seule fois.
 
+#### Grouper les échanges par métier du créateur de l'échange
+
+Groupe les échanges par métier du créateur de l'échange.
+
+Le métier pris en compte est celui associé à l'utilisateur à la date de l'échange.
+
+<!-- PHPFILE: src/Bundle/ChillActivityBundle/Export/Aggregator/CreatorScopeAggregator.php -->
+
 #### Grouper les échanges par problématique liée
 
 <!-- PHPFILE: src/Bundle/ChillActivityBundle/Export/Aggregator/ACPAggregators/BySocialIssueAggregator.php-->