Metadata-Version: 2.5
Name: arctyp
Version: 0.1.4
Summary: CLI d'orchestration pour la composition Typst à la HE-Arc : rend les diagrammes UML via PlantUML interne et compile le PDF en local.
Author-email: Yanis Amani <yanis.amani@he-arc.ch>, Elias Tormos <elias.tormos@he-arc.ch>, Younes Kherbach <younes.kherbach@he-arc.ch>
Requires-Python: >=3.13
Requires-Dist: typst>=0.15.0
Requires-Dist: watchdog>=6.0.0
Description-Content-Type: text/markdown

# 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](#pourquoi-ce-projet)
- [Fonctionnement](#fonctionnement)
- [Installation](#installation)
- [Démarrage rapide](#démarrage-rapide)
- [Commandes](#commandes)
- [Configuration](#configuration)
- [Utilisation hors ligne](#utilisation-hors-ligne)
- [Développement](#développement)
- [Décisions de conception](#décisions-de-conception)
- [Équipe](#é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 :

```typst
#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, avec `uv` ou `pipx` (qui gèrent l'interpréteur et l'isolation).

```bash
uv tool install arctyp
# ou
pipx install arctyp
# ou, sans installation, pour un essai ponctuel :
uvx arctyp --version
```

Le paquet est publié sur [PyPI](https://pypi.org/project/arctyp/). 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](CONTRIBUTING.md), section « Publication d'une version ».

## Démarrage rapide

```bash
# 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

| Commande | Rôle |
|----------|------|
| `arctyp init [répertoire]` | Initie un projet de base complet (conf.typ, template.typ, uml.typ, dossiers diagrams/ et images/, dépôt Git) ; répertoire courant par défaut ; `--force` pour écraser un répertoire non vide |
| `arctyp uml <fichier.puml>` | Rend un diagramme UML via le serveur PlantUML interne ; `--public` pour l'API publique |
| `arctyp compile <rapport.pdf>` | Rendu des diagrammes, compilation du PDF ; le nom de sortie est obligatoire ; `--public` pour le serveur PlantUML public |
| `arctyp watch <rapport.pdf>` | Compile puis recompile à chaque modification (Ctrl-C pour arrêter) ; `--public` pour le serveur PlantUML public |
| `arctyp doctor` | Diagnostic de la configuration et de l'accessibilité des serveurs |

## 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é.

```toml
[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 `plantuml.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.

```bash
# 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** :

```bash
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](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](../wiki/DECISIONS.md). 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).

## Équipe

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