arctyp

Point d'entrée unique pour la composition de documents Typst à la HE-Arc : rend les diagrammes UML via le serveur PlantUML de l'école, initie des projets prêts à l'emploi et compile le PDF localement, sans dépendre d'aucun service externe au moment de la compilation.

État : en cours de développement (projet P3, HES d'été 2026-2027).

Table des matières

• Pourquoi ce projet
• Fonctionnement
• Installation
• Démarrage rapide
• Commandes
• Configuration
• Utilisation hors ligne
• Développement
• Décisions de conception
• Équipe

Pourquoi ce projet

Typst n'effectue aucun accès réseau à la compilation : un document ne peut ni appeler le serveur PlantUML, ni télécharger un template. C'est le rôle de arctyp d'orchestrer ces étapes, qui n'ont pas d'équivalent dans Typst seul. L'utilisateur final ne manipule donc que la CLI, sans connaître l'existence des serveurs sous-jacents.

Fonctionnement

arctyp orchestre la compilation Typst sur le poste de l'utilisateur :

1. rendre les diagrammes .puml en parallèle (pool de threads plafonné) via le serveur PlantUML interne et écrire les SVG à côté des sources ;
2. compiler main.typ en PDF via le paquet Python typst (nom de sortie obligatoire).

Le projet est initialisé par arctyp init : un projet de base prêt à l'emploi (conf.typ, template.typ, uml.typ, main.typ, diagrams/, images/), avec dépôt Git. Les templates officiels se récupèrent directement avec Git (git clone du dépôt templates) — la CLI ne gère pas les templates.

Aucun paquet Typst n'est installé : le projet compile tel quel. L'utilisateur écrit son contenu dans main.typ, et peut modifier les paramètres (couleurs, marges, page de titre…) directement dans les fichiers, sans réinstaller quoi que ce soit :

#import "conf.typ": *

Typst est épinglé dans la CLI, la CI, le web et la documentation : le même PDF est produit partout. Version actuelle : 0.15.0 (paquet Python typst — dernière version publiée sur PyPI ; la 0.15.1 du compilateur n'y est pas encore disponible). Le web (arctyp-web, typst.ts) épinglera la même version de compilateur, écart documenté le temps que les paquets rattrapent la release.

Installation

Prérequis : Python ≥ 3.13 pour une installation globale (avec uv ou pipx), Python ≥ 3.8 suffit pour python arctyp.py sans installation globale (bootstrap via arctyp.py à la racine du projet).

uv tool install arctyp
# ou
pipx install arctyp
# ou
pip install arctyp
# ou, sans installation, pour un essai ponctuel :
uvx arctyp --version
# ou, dans un projet contenant arctyp.py (aucune installation globale requise) :
python arctyp.py --version

Le paquet est publié sur PyPI. Les membres HE-Arc peuvent aussi installer la version du dépôt privé (registre de paquets du projet GitLab) — voir la procédure dans CONTRIBUTING.md, section « Publication d'une version ».

Démarrage rapide

# Initie un projet de base complet avec dépôt Git
arctyp init mon-rapport
cd mon-rapport

# Compile : rend les diagrammes, génère le PDF demandé (nom obligatoire)
arctyp compile mon-rapport.pdf

Commandes

Configuration

Un fichier arctyp.toml à la racine du projet regroupe ses paramètres ; il est écrit par arctyp init. Les secrets (tokens, mots de passe) n'y figurent jamais : il est versionné.

[project]
entry = "main.typ"           # fichier d'entrée Typst

[plantuml]
format = "svg"               # "svg" (défaut) ou "png" — l'extension de sortie suit
# url = "https://plantuml.exemple.ch/"  # URL de base, sans /svg/ ni /png/

[compile]                    # options passées telles quelles à typst.compile
# pdf_standards = "a-2b"     #   PDF/A pour l'archivage
# font_paths = ["polices/"]  #   polices supplémentaires (charte graphique)
# ppi = 144                  #   résolution des conversions d'images
# sys_inputs = { date = "..." }  # valeurs injectées dans le document
# format = "pdf"             #   format de sortie

Choix du serveur PlantUML, par ordre de précédence :

1. --public (options uml, compile, watch, doctor) : API publique, priorité sur tout le reste ;
2. [plantuml] url dans arctyp.toml : serveur spécifique au projet ;
3. à défaut : serveur de l'école https://yk-hes-ete.k8s-ext.ing.he-arc.ch (réseau campus / VPN requis).

url est l'URL de base du serveur, sans le segment de format (/svg/, /png/), ajouté automatiquement selon [plantuml] format.

arctyp doctor vérifie cette configuration et l'accessibilité de la chaîne ; les messages d'erreur sont explicites et actionnables lorsqu'un serveur est injoignable.

Utilisation hors ligne

Dès lors que les diagrammes ont été rendus au moins une fois, un document se recompile hors ligne, sans accès au réseau de l'école.

Développement

Le projet est géré avec uv : l'environnement virtuel, les dépendances et l'installation éditable sont pris en charge par cet outil.

# Installer les dépendances (crée .venv) et synchroniser uv.lock
uv sync

# Lancer la CLI depuis les sources (équivalent à `arctyp ...`)
uv run arctyp --help
uv run python -m arctyp --help

# Vérifier que le verrouillage des dépendances est à jour
uv lock --check

# Lancer la suite de tests (unittest, stdlib — aucune dépendance supplémentaire)
uv run python -m unittest discover -s tests -v

Test rapide :

uv run arctyp --version                  # -> arctyp 0.1.3
uv run arctyp uml diagrams/schema.puml   # rend le diagramme via le serveur PlantUML (foo.puml -> foo.svg)
uv run arctyp compile rapport.pdf        # rend les diagrammes puis compile main.typ en PDF
uv run arctyp doctor                     # diagnostique le projet et la chaîne

Les commandes sont déclarées via des décorateurs dans le paquet arctyp.commands (un fichier par commande) ; voir CONTRIBUTING.md pour la structure, l'ajout d'une commande et les conventions.

Décisions de conception

Les choix structurants sont détaillés, avec leurs alternatives, dans le registre des décisions du wiki. Résumé côté CLI :

• Pas de gestion de templates : les templates se récupèrent par git clone (D-02) — la CLI n'a ni login, ni publish, ni liste.
• Templates = fichiers ordinaires : jamais de paquet @he-arc à installer (D-01) ; arctyp init crée un projet de base prêt à l'emploi.
• Diagrammes avant compilation : Typst n'a pas accès au réseau — la CLI rend les .puml et la fonction uml() des templates charge le résultat (D-03).
• Stdlib-only + typst et watchdog (seules dépendances ; watchdog importée paresseusement) et tests unittest (D-06) ; commandes déclarées par décorateurs dans chaque fichier (D-07).
• Version de Typst épinglée : 0.15.0 côté paquet Python (maximum PyPI), 0.15.1 compilateur — écart documenté (D-08).

Équipe

Elias Tormos, Yanis Amani, Younes Kherbach (projet P3, HES d'été 2026-2027). Encadrement : Le Callennec Benoit, Senn Julien.