arctyp

Point d'entrée unique pour la composition de documents Typst à la HE-Arc : rend les diagrammes UML en interne, copie les templates officiels depuis GitLab dans le projet et compile le PDF, sans dépendre d'aucun service externe.

É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
• Dépôts liés
• É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 via le serveur PlantUML interne et écrire les SVG en cache ;
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 : pipx ou uv installés.

pipx install arctyp
# ou
uv tool install arctyp

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 URLs des serveurs viennent de l'environnement (jamais de ce fichier, qui est versionné) :

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

[plantuml]
format = "svg"               # "svg" (défaut) ou "png" — l'extension de sortie suit

[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

Variables d'environnement : ARCTYP_PLANTUML_URL ou [plantuml] url dans arctyp.toml pour viser un autre serveur PlantUML ; sinon le serveur de l'école (plantuml.he-arc.ch) est utilisé par défaut, et l'option --public (uml, compile, watch, doctor) bascule sur l'API publique. arctyp doctor vérifie cette configuration et l'accessibilité de la chaîne ; les messages d'erreur sont explicites et actionnables lorsque 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.0
uv run arctyp uml diagrams/schema.puml   # rend le diagramme via l'API 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 + watchdog (seule dépendance, 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).

Dépôts liés

Les spécifications fonctionnelles et non fonctionnelles détaillées figurent dans le cahier des charges.

Équipe

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