Skill : add-rust-svgbob

Les références de fichiers (@path) dans ce skill sont relatives à ce répertoire.

Ce que je fais

J'ajoute des diagrammes en art ASCII dans les commentaires de documentation /// de Rust en utilisant la macro transform!() de la crate svgbobdoc. L'art ASCII à l'intérieur des blocs de code ```svgbob est converti en SVG inline au moment de la compilation et intégré sous forme de données URI data:image/svg+xml — aucun fichier externe n'est nécessaire, cela fonctionne à la fois avec cargo doc en local et sur docs.rs.

Le diagramme vit dans le code source lui-même — toute personne lisant le fichier Rust voit directement l'art ASCII.

Quand m'utiliser

Utilisez ce skill quand :

Vous avez une bibliothèque Rust avec des concepts structurels/architecturaux mieux expliqués par un diagramme
Vous voulez des organigrammes rapides, des diagrammes de processus ou des visuels de flux de données sans fichiers image externes
Le diagramme est suffisamment simple pour être représenté avec des caractères ASCII de boîtes
Vous voulez des diagrammes visibles dans le code source (pas cachés dans des PNG externes)
Vous maintenez une crate où le poids de la dépendance svgbobdoc est acceptable

Pas adapté pour :

Les visualisations de données réelles (nuages de points, courbes) — utilisez plutôt embed-doc-image
Les diagrammes complexes avec des courbes ou des détails fins — l'art ASCII a ses limites
Les projets avec des compilateurs Rust très anciens (< 1.54)

Prérequis

Prérequis	Objectif
Rust ≥ 1.54 ou nightly	Pour le support des attributs internes et des macros procédurales
`svgbobdoc` dans les dépendances	La crate de macro procédurale
Fonctionnalité `enable` sur `svgbobdoc`	Active le rendu SVG `svgbob`
Feature flag `doc-images` (ou personnalisé)	Feature-gating pour la compatibilité
Métadonnées docs.rs configurées	Assure que les SVG s'affichent sur docs.rs

Comment je fonctionne

Étape 1 : Vérifier l'état actuel

Lisez Cargo.toml pour vérifier si svgbobdoc est déjà configuré :

svgbobdoc est-il dans [dependencies] avec features = ["enable"] ?
Est-il optionnel (recommandé) ?
Existe-t-il une fonctionnalité doc-images ou similaire pour l'activer ?
[package.metadata.docs.rs] inclut-il features = ["doc-images"] ?

Vérifiez les fichiers source pour une utilisation existante de ```svgbob ou des appels à svgbobdoc::transform!().

Étape 2 : Configurer l'infrastructure (si manquante)

Si svgbobdoc n'est pas configuré, ajoutez-le :

Ajouts dans Cargo.toml :

[dependencies]
svgbobdoc = { version = "0.3", optional = true, features = ["enable"] }

[features]
doc-images = ["dep:svgbobdoc"]

[package.metadata.docs.rs]
features = ["doc-images"]

Si embed-doc-image est également utilisé, combinez sous la même fonctionnalité :

[features]
doc-images = ["dep:embed-doc-image", "dep:svgbobdoc"]

Étape 3 : Analyser le projet

Recherchez récursivement dans <project>/src/ les fichiers *.rs. Identifiez les candidats aux diagrammes — les types et fonctions où un diagramme ASCII clarifierait le concept.

Étape 4 : Identifier les candidats aux diagrammes

Une fonction/type/module est un "candidat au diagramme" quand :

Signal	Exemple
Flux de données	Entrée → Traitement → Sortie
Étapes de processus	Algorithme avec étapes claires
Correspondance de coordonnées	(x, y) → coordonnées transformées
Transformation géométrique	Rotation, projection, mise à l'échelle
Structure arborescente/graphe	Arbre binaire, netlist, graphe de dépendances
Architecture	Hiérarchie des modules, étapes du pipeline
Machine d'états	États et transitions
Comparaison	Avant vs Après, deux alternatives
Disposition	Plan d'étage, disposition mémoire, packing

Étape 5 : Concevoir le diagramme ASCII

Capacités de rendu svgbob :

Élément ASCII	Rendu svgbob
`.─.` / `'─'`	Bordures de rectangle arrondi
`│` / `─`	Lignes
`/` / `\`	Lignes diagonales
`►` / `▼` / `▲` / `◄`	Têtes de flèche (Unicode)
`->` / `<-`	Connecteurs de flèche
`===` / `~~~`	Lignes doubles/ondulées
`( )` / `[ ]`	Parenthèses courbes/anguleuses
`○` / `●`	Marqueurs de cercle
`...`	Connecteurs en pointillés

Conseils de conception pour des diagrammes clairs :

Restez compact — 15 à 25 lignes maximum par diagramme
Utilisez les bordures de boîtes — .───. pour le haut, '───' pour le bas
Étiquetez les flèches — Ajoutez du texte à côté de ──►
Alignez avec les caractères Unicode de boîtes — ─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼
Testez le diagramme — Utilisez l'éditeur svgbob pour prévisualiser

Exemple — un flux de données simple :

.───────────.     .───────────.     .───────────.
│  Entrée   │────►│  Traitement│────►│  Sortie   │
'───────────'     '───────────'     '───────────'

Étape 6 : Ajouter le diagramme

Pour la documentation au niveau des structures :

/// Description existante.
///
/// Le flux de transformation :
#[cfg_attr(feature = "doc-images", doc = svgbobdoc::transform!(
/// ```svgbob
///  .───────────.     .───────────.
///  │  Étape 1  │────►│  Étape 2  │
///  '───────────'     '───────────'
/// ```
))]
pub struct MonType { ... }

Pour la documentation au niveau des fonctions :

/// Description.
#[cfg_attr(feature = "doc-images", doc = svgbobdoc::transform!(
/// ```svgbob
///  .───────────.     .───────────.
///  │  Entrée x │────►│ Sortie f(x)│
///  '───────────'     '───────────'
/// ```
))]
pub fn ma_fonction(x: f64) -> f64 { ... }

IMPORTANT : Les lignes /// à l'intérieur de transform!() doivent être conservées exactement. La macro analyse /// comme des lignes de commentaires de documentation et traite les blocs ```svgbob à l'intérieur.

Étape 7 : Construire et vérifier

# Construction avec diagrammes
cargo doc --features doc-images --no-deps --open

Liste de vérification :

cargo build (sans fonctionnalités) passe — pas de fuite de dépendance svgbobdoc
cargo build --features doc-images passe — la macro transform!() s'exécute
cargo doc --features doc-images --no-deps se termine avec zéro avertissement
Le HTML généré contient des URI data:image/svg+xml;base64,...
Les SVG s'affichent correctement dans le navigateur (flèches, boîtes, texte corrects)

# Vérifier les URI de données SVG sur chaque page de structure
grep -c "data:image/svg" target/doc/ma_crate/struct.MonType.html

Étape 8 : Vérifier les deux états de fonctionnalité

cargo build                          # Doit passer (svgbobdoc non lié)
cargo build --features doc-images    # Doit passer (transform! s'exécute)
cargo test --all-features            # Tous les tests doivent passer

Référence de configuration

Cargo.toml basique (svgbobdoc uniquement)

Configuration minimale pour un projet utilisant uniquement svgbobdoc :

[package]
name = "ma-crate"
version = "0.1.0"
edition = "2024"

[dependencies]
svgbobdoc = { version = "0.3", optional = true, features = ["enable"] }

[features]
doc-images = ["dep:svgbobdoc"]

[package.metadata.docs.rs]
features = ["doc-images"]

Combiné avec embed-doc-image

Lorsque vous utilisez à la fois svgbobdoc (diagrammes ASCII) et embed-doc-image (figures PNG/SVG) :

[dependencies]
embed-doc-image = { version = "0.1", optional = true }
svgbobdoc = { version = "0.3", optional = true, features = ["enable"] }

[features]
doc-images = ["dep:embed-doc-image", "dep:svgbobdoc"]

[package.metadata.docs.rs]
features = ["doc-images"]

Les deux partagent la même fonctionnalité doc-images — une seule commande cargo doc --features doc-images active les deux.

Noms de fonctionnalités personnalisés

Si votre projet a déjà une fonctionnalité doc-images pour d'autres usages, utilisez un nom différent :

[features]
default = []
svg-docs = ["dep:svgbobdoc"]       # Nom personnalisé
doc-images = ["dep:embed-doc-image"] # Nom existant

Puis dans le code source :

#[cfg_attr(feature = "svg-docs", doc = svgbobdoc::transform!(
/// ```svgbob
/// diagramme
/// ```
))]
pub struct MonType;

Résolution de fonctionnalité avec la syntaxe `dep:`

Le préfixe dep: dans les définitions de fonctionnalités a été stabilisé dans Rust 1.60. Il référence explicitement une dépendance optionnelle :

# Syntaxe moderne (Rust ≥ 1.60) — recommandée :
doc-images = ["dep:svgbobdoc"]

# Syntaxe héritée — fonctionne mais moins explicite :
doc-images = ["svgbobdoc"]

La forme dep: est préférée — elle évite l'ambiguïté entre les noms de dépendances et de fonctionnalités.

Options de métadonnées docs.rs

Paramètre	Objectif
`features = ["doc-images"]`	Active svgbobdoc pendant la construction de la doc
`rustdoc-args = ["--html-in-header", "src/doc-header.html"]`	Injecte les en-têtes KaTeX/JS
`all-features = true`	Construit la doc avec TOUTES les fonctionnalités (à utiliser avec précaution)

[package.metadata.docs.rs]
features = ["doc-images"]
rustdoc-args = ["--html-in-header", "src/doc-header.html"]

Compilation conditionnelle avec `cfg_attr`

Le motif principal :

#[cfg_attr(
    feature = "doc-images",                    // condition
    doc = svgbobdoc::transform!(               // attribut à émettre
        /// ```svgbob
        /// diagramme
        /// ```
    )
)]

Comment cela fonctionne à chaque construction :

Commande de construction	`cfg_attr` évalue à	Résultat
`cargo build`	`feature = "doc-images"` est faux	Attribut supprimé — pas de macro, pas de dépendance svgbob
`cargo build --features doc-images`	`feature = "doc-images"` est vrai	`#[doc = svgbobdoc::transform!(...)]` est émis — SVG généré
`cargo doc --features doc-images`	Identique à ci-dessus	URI de données SVG intégrées dans le HTML
docs.rs (les métadonnées définissent les fonctionnalités)	Identique à ci-dessus	SVG s'affiche sur docs.rs

Vérification de la résolution de fonctionnalité

Vérifiez que la fonctionnalité est correctement câblée :

# Vérifier que svgbobdoc N'EST PAS lié dans la construction par défaut
cargo build --verbose 2>&1 | grep svgbobdoc
# (ne devrait produire aucune sortie)

# Vérifier que svgbobdoc EST lié avec la fonctionnalité
cargo build --features doc-images --verbose 2>&1 | grep svgbobdoc
# Sortie : "Compiling svgbobdoc v0.3.0"

Guide de syntaxe de l'art ASCII svgbob

Caractères de boîtes

Le moteur de rendu svgbob reconnaît ces caractères Unicode de boîtes et les convertit en chemins SVG :

Caractère	Point de code	Rendu sous forme
`─`	U+2500	Ligne horizontale
`│`	U+2502	Ligne verticale
`┌`	U+250C	Coin supérieur gauche
`┐`	U+2510	Coin supérieur droit
`└`	U+2514	Coin inférieur gauche
`┘`	U+2518	Coin inférieur droit
`├`	U+251C	Jonction en T gauche
`┤`	U+2524	Jonction en T droite
`┬`	U+252C	Jonction en T supérieure
`┴`	U+2534	Jonction en T inférieure
`┼`	U+253C	Jonction croisée
`╱`	U+2571	Diagonale montante droite
`╲`	U+2572	Diagonale montante gauche
`◄`	U+25C4	Tête de flèche gauche
`►`	U+25BA	Tête de flèche droite
`▲`	U+25B2	Tête de flèche haut
`▼`	U+25BC	Tête de flèche bas
`●`	U+25CF	Cercle rempli
`○`	U+25CB	Cercle vide
`═`	U+2550	Double horizontale
`║`	U+2551	Double verticale
`≈`	U+2248	Ligne ondulée
`→`	U+2192	Flèche vers la droite

Créer des boîtes

Rectangle arrondi (le plus courant pour les nœuds de diagramme) :

.───────────.
│ contenu  │
'───────────'

Utilisez . pour le coin supérieur gauche, ' pour le coin supérieur droit
Utilisez ' pour le coin inférieur gauche, . pour le coin inférieur droit
Remplissez les bordures supérieure et inférieure avec ─
Remplissez les bordures latérales avec │

Rectangle pointu :

┌───────────┐
│ contenu  │
└───────────┘

Connecter des boîtes avec des flèches

Flèche horizontale :

.───.         .───.
│ A │────────►│ B │
'───'         '───'

Flèche verticale :

.───.
│ A │
'───'
  │
  ▼
.───.
│ B │
'───'

Flèche depuis un côté spécifique :

         .───.
         │ B │
         '───'
           ▲
           │
.───.      │
│ A │──────┘
'───'

Ajouter des étiquettes aux flèches

Placez le texte à côté de la ligne de flèche. svgbob le positionne automatiquement :

.───.     condition    .───.
│ A │══════════════════►│ B │
'───'                  '───'

.───.     faux      .───.
│ A │──────────────►│ B │
'───'              '───'

Texte multiligne dans les boîtes

svgbob adapte automatiquement le texte en fonction de la largeur de la boîte :

.──────────────────.
│ Ce texte sera    │
│ coupé à l'inté-  │
│ rieur des limites│
│ de la boîte      │
'──────────────────'

Lignes diagonales

.───.     .───.
│ A │╲    │ C │
'───' ╲   '───'
       ╲
        ╲ .───.
         ╲│ B │
          ╲'───'

Arbres et hiérarchies

Arbre binaire :

       .───.
       │ R │
       '───'
       ╱   ╲
   .───.     .───.
   │ G │     │ D │
   '───'     '───'
   ╱   ╲       ╲
 .───. .───.   .───.
 │GG │ │GD │   │DD │
 '───' '───'   '───'

Hiérarchie indentée (sans lignes) :

.───────────────.
│ Racine        │
│ ├── Enfant A  │
│ ├── Enfant B  │
│ └── Enfant C  │
'───────────────'

Grilles et matrices

.──────┬──────┬──────.
│  a   │  b   │  c   │
├──────┼──────┼──────┤
│  d   │  e   │  f   │
├──────┼──────┼──────┤
│  g   │  h   │  i   │
'──────┴──────┴──────'

Dispositions de comparaison

Côte à côte :

.─────────────.  .─────────────.
│ Avant       │  │ Après       │
│  .───────.  │  │  .───────.  │
│  │ Ancien │  │  │  │ Nouveau│  │
│  '───────'  │  │  '───────'  │
'─────────────'  '─────────────'

Avant → Après (séquentiel) :

.───────────────.     .───────────────.
│  Chemin lent  │────►│  Chemin rapide│
│  O(n²)        │     │  O(n log n)   │
'───────────────'     '───────────────'

Schémas de base de données / tables

.──────────────────────.
│  Table : utilisateurs │
├──────────────────────┤
│  id         INTEGER  │──► PK
│  nom        TEXT     │
│  email      TEXT     │──► UNIQUE
│  créé_le   DATETIME │
'──────────────────────'

Organigramme avec décision

.───────────.
│  Début    │
'─────┬─────'
      │
      ▼
.───────────.
│  Processus│
'─────┬─────'
      │
      ▼
.───────────.   oui   .───────────.
│  Test ?  │─────────►│  Option A │
'─────┬─────'         '───────────'
      │
      │ non
      ▼
.───────────.
│  Option B │
'───────────'

Architecture en couches

.───────────────────────────.
│  Couche Application      │
├───────────────────────────┤
│  Couche Logique Métier   │
├───────────────────────────┤
│  Couche d'Accès aux Données│
├───────────────────────────┤
│  Base de données          │
'───────────────────────────'

Diagramme de séquence / timing (simple)

Client───┬──────────────────┐
         │   Requête        │
         │─────────────────►│
         │                  │
         │   Réponse        │
         │◄─────────────────│
Serveur──┴──────────────────┘

Dépannage

Problèmes courants

Problème	Cause probable	Solution
Les SVG ne s'affichent pas	`cfg_attr` non activé	Vérifiez que `--features doc-images` est passé
Erreur de compilation	Syntaxe incorrecte dans `transform!()`	Assurez-vous que les `///` sont exacts
Avertissements à la construction	Diagramme trop large (>80 colonnes)	Réduisez la largeur du diagramme
Pas de rendu sur docs.rs	Métadonnées manquantes	Ajoutez `features = ["doc-images"]` dans `[package.metadata.docs.rs]`
Dépendance svgbobdoc dans la build normale	`optional = true` manquant	Marquez comme optionnel

Conseils de débogage

Vérifiez le HTML généré pour les URI de données SVG :

grep "data:image/svg" target/doc/*/index.html | head -5

Isolez le diagramme dans un test :

#[test]
fn test_diagramme() {
    let svg = svgbobdoc::transform!(
        /// ```svgbob
        /// .───.
        /// │ A │
        /// '───'
        /// ```
    );
    println!("{}", svg);
}

Utilisez l'éditeur en ligne pour prototyper :
- Éditeur svgbob

Workflow complet

# 1. Configurer Cargo.toml
echo 'svgbobdoc = { version = "0.3", optional = true, features = ["enable"] }' >> Cargo.toml
echo '[features]' >> Cargo.toml
echo 'doc-images = ["dep:svgbobdoc"]' >> Cargo.toml
echo '[package.metadata.docs.rs]' >> Cargo.toml
echo 'features = ["doc-images"]' >> Cargo.toml

# 2. Ajouter des diagrammes aux fichiers source

# 3. Tester
export RUSTFLAGS="-D warnings"
cargo doc --features doc-images --no-deps 2>&1 | grep -E "warning|error" || echo "OK"

# 4. Vérifier
grep -rl "data:image/svg" target/doc/*/index.html

# 5. Valider
cargo test
"```

## License

Adapté de la documentation originale de [svgbobdoc](https://crates.io/crates/svgbobdoc) et [svgbob](https://github.com/ivanceras/svgbob).

Demander à votre IA préférée

Documentation