📦 `quartify`

TL;DR

Description

quartify est un package R qui convertit automatiquement des scripts R en documents Quarto markdown (.qmd).

Le package facilite la transformation de vos analyses R en documents Quarto reproductibles et bien structurés, en préservant la structure logique de votre code grâce aux sections de code RStudio. Il reconnaît la syntaxe standard des sections de code RStudio (####, ====, ----) pour créer des structures de navigation correctement indentées.

Différences avec knitr::spin() et les render-scripts de Quarto

knitr::spin() et la fonctionnalité render-scripts de Quarto permettent déjà de rendre des scripts R, mais reposent tous deux sur l'insertion de structure Markdown directement dans les commentaires (#', titres, options de chunks, etc.).

quartify adopte une philosophie différente : il n'impose aucune syntaxe Markdown dans les commentaires et fonctionne sur des scripts R totalement standards. Les commentaires restent des commentaires, le code reste du code.

L'objectif est de conserver des scripts propres et habituels, tout en les rendant convertibles en .qmd — et, lorsque plusieurs scripts sont sélectionnés, de pouvoir les assembler automatiquement en un book Quarto structuré sans aucune réécriture du code source.

Cas d'usage

Si vous avez un script R fonctionnel qui contient des commentaires, vous pourriez vouloir générer un document Quarto à partir de ce script qui vous permettra de produire automatiquement une documentation HTML affichable. Ceci est particulièrement utile pour :

Documentation : Générez automatiquement de la documentation à partir de votre code commenté
Revue de code : Présentez votre code dans un format plus lisible pour les parties prenantes qui préfèrent les documents formatés aux scripts bruts

Fonctionnalités

Conversion automatique : Transforme vos scripts R (.R) en documents Quarto (.qmd)
Conversion de fichiers multiples : Convertir des fichiers individuels, plusieurs fichiers, ou des répertoires entiers en une seule fois
Création de Quarto Books : Génération automatique de livres Quarto navigables à partir de répertoires (activé par défaut)
Support des sections de code RStudio : Reconnaît les sections de code RStudio (####, ====, ----) et les convertit en titres markdown appropriés avec les niveaux d'indentation corrects
Préservation des commentaires : Les commentaires réguliers sont convertis en texte explicatif
Organisation du code : Le code R est automatiquement organisé en blocs exécutables
En-tête YAML personnalisable : Possibilité de définir le titre, l'auteur et d'autres paramètres
Table des matières : Génération automatique d'une table des matières dans le document Quarto avec la profondeur appropriée
- Support du français : Affiche "Sommaire" au lieu de "Table of contents" quand la langue est le français
Génération HTML automatique : Génère optionnellement le fichier HTML à partir du .qmd et l'ouvre dans le navigateur
Thèmes personnalisables : Choisissez parmi 25+ thèmes Quarto pour personnaliser l'apparence de vos documents HTML
Numéros de ligne source : Affichage optionnel des numéros de ligne originaux du script R dans les chunks de code pour la traçabilité
Intégration qualité du code : Intégration optionnelle avec styler et lintr pour afficher les suggestions de formatage et les problèmes de qualité dans des onglets interactifs
Support de la documentation roxygen2 : Conversion automatique des blocs de documentation roxygen2 (#') en sections callout-note avec les noms des fonctions
Support des snippets RStudio : Insertion rapide de métadonnées et de structure via des snippets de code personnalisables
Fonctionnalités spéciales : Support des diagrammes Mermaid, des callouts (note, tip, warning, etc.), et des tabsets pour organiser le contenu
Personnalisation du répertoire de sortie : Spécifiez des répertoires de sortie personnalisés pour la génération de livres (par défaut _book)
Prêt pour déploiement web : Inclut quartify_app_web() pour déploiement sur serveurs web avec capacités d'upload/téléchargement

Installation

install.packages("quartify")

Vous pouvez installer la version de développement de quartify depuis GitHub :

# install.packages("devtools")
devtools::install_github("ddotta/quartify")

Utilisation

🌐 Essayez l'Application Web en Ligne !

Aucune installation requise ! Utilisez quartify directement dans votre navigateur :

→ https://quartify.lab.sspcloud.fr/ ←

La version web vous permet de :

✅ Télécharger un ou plusieurs scripts R directement depuis votre ordinateur OU sélectionner un répertoire contenant des scripts R pour une conversion par lots
✅ Créer des Quarto Books automatiquement à partir de plusieurs fichiers avec structure de navigation
✅ Configurer les options de conversion (titre, auteur, thème, création de book, etc.)
✅ Télécharger les fichiers .qmd et .html générés (ou une archive .zip en mode batch)
✅ Aucune installation de R nécessaire !

Interface Shiny Interactive (pour les utilisateurs R)

quartify fournit également une interface Shiny interactive qui fonctionne dans n'importe quel environnement R :

Option 1 : Application Autonome (fonctionne dans la plupart des IDE)

library(quartify)
quartify_app()  # S'ouvre dans votre navigateur par défaut

Cela lance une interface basée sur le navigateur où vous pouvez :

Convertir un ou plusieurs fichiers OU un répertoire entier de scripts R
Créer des Quarto Books avec navigation automatique (activé par défaut pour les répertoires)
Sélectionner un répertoire de sortie personnalisé pour la génération de books
Sélectionner les fichiers/répertoires d'entrée avec un explorateur de fichiers
Choisir l'emplacement du fichier de sortie pour les fichiers individuels
Personnaliser le titre du document, l'auteur et le thème
Activer/désactiver les options de rendu et d'affichage
Basculer entre l'interface anglaise/française

Parfait pour les utilisateurs de Positron, VS Code, ou tout IDE supportant R !

Option 2 : Add-in RStudio

Si vous utilisez RStudio, vous pouvez également accéder à la même interface via :

Ouvrez votre script R dans RStudio
Allez dans le menu Addins → Quartify → Convert R Script to Quarto
Une fenêtre de dialogue apparaîtra avec les mêmes options que l'application autonome
Cliquez sur GENERATE pour convertir votre script

L'interface détecte automatiquement les préférences de langue de votre session R et affiche tous les libellés en anglais ou en français en conséquence. Vous pouvez changer la langue à tout moment avec les boutons EN/FR. Le format de sortie est toujours HTML.

Exemple basique

library(quartify)

# Convertir un script R en document Quarto et générer le HTML
rtoqmd("mon_script.R", "mon_document.qmd")

# Convertir seulement, sans générer le HTML
rtoqmd("mon_script.R", "mon_document.qmd", render = FALSE)

Personnalisation

# Avec personnalisation du titre et de l'auteur
rtoqmd("mon_script.R", 
       output_file = "mon_document.qmd",
       title = "Mon analyse statistique",
       author = "Votre nom",
       format = "html",
       theme = "cosmo",          # Thème Quarto (optionnel)
       render = TRUE,            # Générer le HTML 
       open_html = TRUE,         # Ouvrir le HTML dans le navigateur
       number_sections = TRUE)   # Numéroter les sections automatiquement

Utilisation du fichier exemple

Un fichier exemple est inclus dans le package pour tester la fonction :

# Localiser le fichier exemple
example_file <- system.file("examples", "example.R", package = "quartify")

# Convertir le fichier exemple
rtoqmd(example_file, "test_output.qmd")

Conversion par lots

Utilisation de l'Interface Web

Dans quartify_app_web() (ou l'application en ligne), vous pouvez :

Sélectionner le mode "Batch (multiple files)"
Choisir votre méthode d'entrée :
- Upload files : Télécharger plusieurs scripts R en même temps
- Select directory : Parcourir et sélectionner un répertoire contenant vos scripts R
L'application convertira tous les scripts R et créera une archive .zip téléchargeable

Parfait pour convertir des projets entiers sans écrire de code R !

Utilisation des Fonctions R

Convertir tous les scripts R d'un répertoire (y compris les sous-répertoires) :

# Convertir tous les scripts R d'un répertoire
rtoqmd_dir("chemin/vers/scripts")

# Convertir et générer tous les scripts
rtoqmd_dir("chemin/vers/scripts", render = TRUE)

# Avec paramètres personnalisés
rtoqmd_dir("chemin/vers/scripts", 
           author = "Équipe Data",
           exclude_pattern = "test_.*\\.R$")

Intégration de la qualité du code

quartify s'intègre optionnellement avec styler et lintr pour vous aider à améliorer la qualité du code :

Fonctionnalités

use_styler : Affiche le code formaté selon le guide de style tidyverse
use_lintr : Identifie les problèmes de qualité du code et les problèmes potentiels
apply_styler : Applique directement le formatage à votre script R original (⚠️ modifie le fichier source)

Lorsque des problèmes de qualité sont détectés, quartify crée des onglets interactifs dans la sortie HTML avec :

Code Original : Votre code original
Code Stylisé : Version formatée (si use_styler = TRUE et des changements détectés)
Problèmes Lint : Avertissements de qualité (si use_lintr = TRUE et des problèmes trouvés)

Installation

Ces packages sont optionnels et nécessaires uniquement si vous souhaitez utiliser les fonctionnalités de qualité du code :

install.packages(c("styler", "lintr"))

Exemples

# Afficher les suggestions de formatage dans des onglets
rtoqmd("mon_script.R", "sortie.qmd", 
       use_styler = TRUE)

# Afficher à la fois le formatage et les problèmes lint
rtoqmd("mon_script.R", "sortie.qmd",
       use_styler = TRUE,
       use_lintr = TRUE)

# Appliquer le formatage directement au fichier source (⚠️ modifie l'original)
rtoqmd("mon_script.R", "sortie.qmd",
       apply_styler = TRUE)

Dans les applications Shiny

Les trois applications Shiny (rtoqmd_addin(), quartify_app(), et quartify_app_web()) incluent des cases à cocher pour ces options dans l'interface.

📖 Pour des informations détaillées, consultez :

Guide de qualité du code
Vignette Fonctionnalités avancées - Guide complet avec exemples
Vignettes du package

Format du script R source

Pour que la conversion fonctionne correctement, structurez votre script R en utilisant les sections de code RStudio :

# Titre : Analyse des données Iris
#
# Auteur : Jean Dupont
#
# Date : 2025-11-28
#
# Description : Explorer les différences entre les espèces d'iris
#

library(dplyr)

## Titre 2 ####

### Titre 3 ====

# Début du traitement statistique
# Comptage du nombre d'observations par espèce

iris |> 
  count(Species)

### Titre 3 ====

# Filtrer le data.frame sur l'espèce "setosa"

iris |> 
  filter(Species == "setosa")

#### Titre 4 ----

# Sélectionner la colonne Species

iris %>% 
  # Sélectionner une colonne
  select(Species)

Règles de commentaires

0. Métadonnées du document (Optionnel)

Vous pouvez définir les métadonnées directement dans votre script R en utilisant des commentaires spéciaux au début :

Titre : # Title : Mon titre ou # Titre : Mon titre
Auteur : # Author : Mon nom ou # Auteur : Mon nom
Date : # Date : AAAA-MM-JJ
Description : # Description : Description de votre script

💡 Snippet RStudio : utilisez la fonction install_quartify_snippets() pour installer les snippets de quartify ou créez un snippet pour insérer rapidement les métadonnées (Outils > Modifier les snippets de code > R) :

snippet header
	# Titre : ${1}
	#
	# Auteur : ${2}
	#
	# Date : ${3}
	#
	# Description : ${4}
	#

Tapez header + Tab dans votre script pour insérer la structure de métadonnées.

Comportement :

Les métadonnées trouvées dans le script remplacent les paramètres de la fonction
Les lignes de métadonnées sont retirées du corps du document (uniquement dans le YAML)
Si aucune métadonnée dans le script, les paramètres de la fonction sont utilisés

📝 Note : Le champ Description peut s'étendre sur plusieurs lignes. Pour continuer la description, commencez la ligne suivante par # suivi d'au moins un espace. Les lignes de continuation sont automatiquement concaténées. Exemple :
# Description : Cette analyse explore les différences entre les espèces d'iris
# en utilisant diverses méthodes statistiques et techniques de visualisation
# pour identifier les patterns et corrélations.

quartify reconnaît trois types de lignes dans votre script R :

1. Sections de code (En-têtes)

Les sections de code RStudio deviennent des en-têtes markdown. Critique : les symboles de fin doivent contenir au moins 4 caractères :

## Titre ---- → En-tête de niveau 2 (au moins 4 #, = ou - à la fin)
### Titre ---- → En-tête de niveau 3 (au moins 4 #, = ou - à la fin)
#### Titre ---- → En-tête de niveau 4 (au moins 4 #, = ou - à la fin)

Note : Vous pouvez utiliser #, =, ou - indifféremment comme symboles de fin (ex : ## Titre ==== ou ### Titre ---- fonctionneront).

2. Commentaires réguliers (Texte)

Les commentaires simples avec # en début de ligne (sans espace avant) suivis d'un espace deviennent du texte explicatif :

# Ceci est un commentaire autonome
# Il devient du texte simple dans le document Quarto

Commentaires cachés : Les commentaires qui commencent par # immédiatement suivi d'un caractère non-espace (ex: #NOTE:, #TODO:, #DEBUG) sont complètement ignorés et n'apparaîtront pas dans la sortie. Cela permet d'inclure des notes de développement privées :

# Ce commentaire apparaît dans la sortie

#TODO: À corriger plus tard - NON visible dans la sortie
#NOTE: Rappel interne - NON visible

# Ce commentaire apparaît à nouveau

⚠️ Important : Pour qu'un commentaire soit converti en texte, la ligne doit commencer par # suivi d'un espace. Les commentaires indentés (avec des espaces avant #) restent dans le code.

💡 Astuce : Pour diviser un long chunk en plusieurs parties, insérez un commentaire en début de ligne (sans espace avant #) entre deux blocs de code. Ce commentaire sera converti en texte et créera naturellement deux chunks séparés.

Astuce : Utilisez le raccourci Commenter/Décommenter de RStudio (Ctrl+Shift+C sur Windows/Linux ou Cmd+Shift+C sur Mac) pour ajouter ou retirer rapidement des commentaires.

3. Lignes de code

Les lignes non commentées deviennent des chunks de code R exécutables :

iris |> filter(Species == "setosa")

4. Commentaires en ligne (À l'intérieur du code)

Les commentaires à l'intérieur des blocs de code sont préservés dans le chunk de code R :

iris %>% 
  # Ce commentaire reste dans le bloc de code
  select(Species)

5. Callouts (Encadrés)

Les callouts sont des blocs spéciaux qui mettent en évidence des informations importantes. Cinq types sont supportés : note, tip, warning, caution, important.

Syntaxe dans le script R :

# callout-note - Note importante
# Ceci est le contenu du callout.
# Il peut s'étendre sur plusieurs lignes.

# Une ligne vide ou du code termine le callout
x <- 1

Se convertit en Quarto :

::: {.callout-note title="Note importante"}
Ceci est le contenu du callout.
Il peut s'étendre sur plusieurs lignes.
:::

Sans titre :

# callout-tip
# Ceci est un conseil sans titre.

Les callouts se terminent lorsqu'on rencontre une ligne vide, du code, ou une autre section.

6. Diagrammes Mermaid

Créez des organigrammes, des diagrammes de séquence et d'autres visualisations avec la syntaxe Mermaid, rendus directement dans la sortie HTML.

Syntaxe dans le script R :

#| mermaid
#| eval: true
# flowchart LR
#   A[Démarrer] --> B{Décision}
#   B -->|Oui| C[Résultat 1]
#   B -->|Non| D[Résultat 2]

Se convertit en Quarto :

```{mermaid}
%%| eval: true
flowchart LR
  A[Démarrer] --> B{Décision}
  B -->|Oui| C[Résultat 1]
  B -->|Non| D[Résultat 2]


**Remarque :** Les lignes du diagramme sont préfixées avec `#` dans le script R pour maintenir une syntaxe R valide. Le préfixe `#` est automatiquement supprimé lors de la conversion en Quarto.

Pour plus d'informations : [Documentation Mermaid](https://mermaid.js.org/)

#### 7. Tabsets (Onglets)

Organisez du contenu connexe dans des onglets interactifs pour afficher des vues alternatives ou des analyses groupées.

**Syntaxe dans le script R :**

```r
# tabset
# tab - Statistiques résumées
# Voici les statistiques pour iris :
summary(iris)

# tab - Structure
# Structure des données :
str(iris)

# tab - Premières lignes
# Premières observations :
head(iris)

Se convertit en Quarto :

::: {.panel-tabset}

## Statistiques résumées

Voici les statistiques pour iris :

```{r}
summary(iris)

Structure

Structure des données :

str(iris)

Premières lignes

Premières observations :

head(iris)

:::


Pour plus d'informations : [Quarto Tabsets](https://quarto.org/docs/interactive/layout.html#tabset-panel)

**Règles importantes :**

- Toujours inclure un espace après `#` pour les commentaires
- Les en-têtes de section DOIVENT avoir au moins 4 symboles de fin
- **Les commentaires avec un `#` en début de ligne** → deviennent du texte en dehors des blocs de code
- **Les commentaires dans le code** → restent à l'intérieur des blocs de code
- **Callouts** → `# callout-TYPE` ou `# callout-TYPE - Titre`
- **Mermaid** → `#| mermaid` suivi du contenu du diagramme
- **Tabsets** → `# tabset` puis `# tab - Titre` pour chaque onglet
- Les lignes de code consécutives sont regroupées dans le même bloc
- Les lignes vides entre les blocs sont ignorées

Ceci suit la [convention des sections de code RStudio](https://docs.posit.co/ide/user/ide/guide/code/code-sections.html) qui fournit une indentation appropriée dans la navigation du plan du document RStudio.

## Thèmes Quarto

Personnalisez l'apparence de vos documents HTML avec les thèmes Quarto. Le package supporte tous les thèmes Bootswatch disponibles :

**Thèmes clairs** : cosmo, flatly, journal, litera, lumen, lux, materia, minty, morph, pulse, quartz, sandstone, simplex, sketchy, spacelab, united, vapor, yeti, zephyr

**Thèmes sombres** : darkly, cyborg, slate, solar, superhero

Exemple :

```r
# Utiliser le thème "flatly"
rtoqmd("mon_script.R", theme = "flatly")

# Utiliser le thème sombre "darkly"
rtoqmd("mon_script.R", theme = "darkly")

Pour plus d'informations sur les thèmes, consultez la documentation Quarto.

Sortie et documentation

Le document .qmd généré contient :

Un en-tête YAML complet avec configuration de la table des matières
Des titres correctement structurés à partir des sections de code RStudio
Des explications textuelles à partir de vos commentaires
Chunks de code non exécutables pour une documentation statique

📝 Pour un exemple complet de la sortie générée, consultez la vignette Démarrage

Intégration CI/CD

Utilisez quartify dans vos pipelines CI/CD pour générer automatiquement la documentation :

GitHub Actions (.github/workflows/generate-docs.yml) :

- name: Générer la documentation
  run: |
    library(quartify)
    rtoqmd_dir("scripts/", render = TRUE, author = "Équipe Data")
  shell: Rscript {0}

- uses: actions/upload-artifact@v4
  with:
    name: documentation
    path: |
      scripts/**/*.qmd
      scripts/**/*.html

GitLab CI (.gitlab-ci.yml) :

generate-docs:
  image: ddottaagr/quartify:latest
  script:
    - R -e "quartify::rtoqmd_dir('scripts/', render = TRUE, author = 'Équipe Data')"
  artifacts:
    paths:
      - scripts/**/*.qmd
      - scripts/**/*.html

📘 Guide complet CI/CD avec exemples détaillés : Intégration CI/CD

Licence

MIT

FilesExpand file tree

README_FR.md

Latest commit

History

README_FR.md

File metadata and controls

📦 quartify

TL;DR

Description

Différences avec knitr::spin() et les render-scripts de Quarto

Cas d'usage

Fonctionnalités

Installation

Utilisation

🌐 Essayez l'Application Web en Ligne !

→ https://quartify.lab.sspcloud.fr/ ←

Interface Shiny Interactive (pour les utilisateurs R)

Option 1 : Application Autonome (fonctionne dans la plupart des IDE)

Option 2 : Add-in RStudio

Exemple basique

Personnalisation

Utilisation du fichier exemple

Conversion par lots

Utilisation de l'Interface Web

Utilisation des Fonctions R

Intégration de la qualité du code

Fonctionnalités

Installation

Exemples

Dans les applications Shiny

Format du script R source

Règles de commentaires

0. Métadonnées du document (Optionnel)

1. Sections de code (En-têtes)

2. Commentaires réguliers (Texte)

3. Lignes de code

4. Commentaires en ligne (À l'intérieur du code)

5. Callouts (Encadrés)

6. Diagrammes Mermaid

Structure

Premières lignes

Sortie et documentation

Intégration CI/CD

Licence

📦 `quartify`