De la Donnée au Document : Un Guide Complet pour Débuter avec Quarto

Créez des rapports dynamiques, reproductibles et professionnels

Auteur·rice
Affiliation

Wilson Toussile

ENSPY & ESSFAR

1 Introduction

Quarto est un système de publication scientifique et technique open-source de nouvelle génération. Il vous permet de combiner du texte narratif avec du code (en Python, R, Julia, et Observable) pour créer des documents soignés et entièrement reproductibles.

1.1 ✨ Pourquoi choisir Quarto ?

  • Multi-langage : Écrivez du code en Python, R, et Julia dans le même document.
  • Multi-format : Exportez le même fichier source en HTML, PDF, MS Word, présentations (Power Point, Beamer, ReavelJs), dashboards, et plus encore.
  • Reproductibilité : Votre document final contient à la fois le code et ses résultats. N’importe qui peut ré-exécuter votre analyse.
  • Simplicité : La syntaxe Markdown est facile à apprendre, et les options avancées sont claires et puissantes.

1.2 Public Cible

Toute personne (analyste, chercheur, étudiant) qui manipule des données et souhaite communiquer ses résultats de manière claire, professionnelle et reproductible.

1.3 Objectifs de ce guide

  • Installer Quarto et comprendre la structure d’un document (.qmd).
  • Mélanger texte (Markdown) et code (Python, R…) dans un même fichier.
  • Contrôler l’affichage et l’exécution du code.
  • Mettre en forme vos documents avec des composants avancés.
  • Exporter votre travail dans plusieurs formats.
  • ✨ Découvrir des fonctionnalités clés comme les références croisées et la bibliographie.

1.4 ✨ Avant de Commencer : Installation

Avant toute chose, vous devez installer Quarto. C’est très simple :

  1. Téléchargez le Quarto CLI depuis le site officiel.

  2. Utilisez un éditeur de code qui a une bonne intégration avec Quarto, comme

Une fois installé, vous pouvez créer un nouveau fichier avec l’extension .qmd et commencer à écrire !

2 Partie 1 : L’Anatomie d’un Document Quarto

Un document Quarto est un simple fichier texte .qmd composé de trois éléments.

2.1 L’en-tête YAML

C’est le “panneau de contrôle” de votre document, situé tout en haut et délimité par ---. Il définit les métadonnées (titre, auteurn date, …) et les options de formatage.

Exemple d’en-tête YAML 
---
1title: "Mon Premier Rapport"
2author: "Votre Nom"
3date: "today"
4format: html
---
1
Le titre du document
2
Nom de l’auteur
3
Date de compilation du document. Vous pouvez fixer une date (ex: “2025-07-14”)
4
Format du fichier de sortie.
Autre exemple d’en-tête YAML 
---
title: "Mon Rapport"
subtitle: "Un sous-titre"
author:
  - name: Nom Prénom
    email: prenom.nom@mail.net
    institute: Mon Institut
date: today
1execute:
  echo: true
  eval: true
  code-fold: true
2format:
  html:
3    toc: true
4    toc-depth: 2
5    theme: cosmo
  pdf:
6    documentclass: scrreprt
    toc: true
    toc-depth: 2
7    number-sections: true
8    number-depth: 2
---
1
Paramètres pour l’exécution du code (R, Python, Julia, …)
2
Possibilité de définir plusieurs formats de sortie.
3
Activer ou non la table des matières.
4
La profondeur de la table des matières.
5
Plusieurs thèmes sont disponibles.
6
Classe \(\LaTeX\) pour la sortie PDF.
7
Activer ou non la numérotation des sections et sous-sections.
8
La profondeur de numérotation des sections et sous-sections.
Important

Pour plus de détails, consultez le site de la documentation de Quarto.

2.2 Le Texte en Markdown

Tout le contenu narratif est écrit en Markdown, une syntaxe simple pour formater du texte.

# Titre de niveau 1

Ceci est une section de texte. On peut mettre du texte en **gras** ou en *italique*.

Voici une liste à puces:
- Item 1
- Item 2

Voici une liste numérotée, avec sous-listes:
1. Item 1
  a. Sous-item a
  b. Sous-item b
2. Item 2

## Sous-section 1

Voici une sous-section.
Important

Vous trouverez les bases du Markdown ici.

2.3 Les Blocs de Code (Code Chunks)

C’est ici que la magie opère. Vous insérez votre code dans des blocs délimités par ```{python} (ou {r}, {julia}). Lorsque vous “rendrez” le document, Quarto exécutera ce code et inclura les résultats (texte, tableaux, graphiques) dans le document final.

```{python}
import pandas as pd
import seaborn as sns

df = sns.load_dataset('iris')
df.head()
```

3 Partie 2 : Le Cœur de Quarto : Le Code

3.1 Maîtriser les options des blocs de code

Vous pouvez contrôler précisément comment chaque bloc de code se comporte grâce aux options #|.

  • #| echo: false : Le code ne sera pas affiché (mais il sera exécuté).
  • #| eval: false : Le code sera affiché, mais pas exécuté.
  • #| include: false : Le code est exécuté, mais ni le code ni sa sortie ne sont affichés.
  • #| fig-cap: "..." : Ajoute une légende à un graphique.
  • #| label: fig-iris : ✨ Ajoute une étiquette pour pouvoir référencer le graphique plus tard.

```{python}
#| label: fig-iris-scatter
#| fig-cap: "Relation entre la longueur et la largeur des sépales."

sns.scatterplot(data=df, x='sepal_length', y='sepal_width', hue='species')
```

3.2 ✨ Le Code en Ligne (Inline Code)

Une fonctionnalité extrêmement puissante est la capacité d’insérer des résultats de code directement dans votre texte. Cela garantit que vos chiffres sont toujours à jour avec vos données.

La syntaxe est `!expr python_code` pour Python ou `r r_code` pour R.

Le jeu de données Iris contient `!expr len(df)` observations. 
La longueur moyenne des sépales est de `!expr df['sepal_length'].mean().round(2)` cm.

4 Partie 3 : Mettre en Forme comme un Pro

Quarto offre des outils puissants pour organiser votre contenu.

4.1 Les Avertissements (Callouts)

Parfait pour attirer l’attention sur une information importante.

:::{.callout-note}
Ceci est une note. L'espèce Setosa est clairement séparée des autres.
:::
:::{.callout-important}
Ceci est une note importante. L'espèce Setosa est clairement séparée des autres.
:::

4.2 La Mise en Page en Colonnes et les Onglets

Idéal pour présenter différentes facettes d’une analyse sans surcharger la page.

:::{.panel-tabset}

### Graphique

Le graphique est visible dans la Figure @fig-iris-scatter.

### Données

```{python}
#| echo: false
df.describe()
```

:::

4.3 ✨ Les Références Croisées

Grâce aux étiquettes (#| label: ...), vous pouvez facilement faire référence à vos figures, tableaux ou sections.

Exemple :

Comme nous pouvons le voir dans la **Figure @fig-iris-scatter**, 
il existe une corrélation claire...

5 Partie 4 : Exporter, Partager et Aller Plus Loin

5.1 Le Rendu

Pour transformer votre fichier .qmd en un document final, vous avez plusieurs options selon votre environnement de travail.

Terminal (Ligne de commande)

C’est la méthode universelle. Ouvrez un terminal dans le dossier de votre projet et exécutez :

quarto render mon_document.qmd

✨ RStudio IDE

L’intégration de Quarto dans RStudio rend le processus très simple.

  • Cliquez sur le bouton Render situé au-dessus de votre éditeur de texte.
  • Ou utilisez le raccourci clavier Ctrl+Shift+K (Windows/Linux) ou Cmd+Shift+K (macOS).

✨ VS Code / Positron

Si vous utilisez VS Code ou Positron avec l’extension Quarto officielle :

  • Cliquez sur le lien Render ou Preview en haut à droite de la fenêtre de l’éditeur.
  • Ou, ouvrez la palette de commandes avec Ctrl+Shift+P (Windows/Linux) ou Cmd+Shift+P (macOS) et tapez Quarto: Render Document.

5.2 Personnaliser la sortie avec YAML

Pour générer un PDF, par exemple, changez format: html en format: pdf (cela nécessite une installation LaTeX). Vous pouvez aussi spécifier plusieurs formats et leurs options.

---
title: "Rapport Avancé"
format:
  html:
    toc: true
    toc-depth: 2
    code-fold: true
    theme: cosmo
  pdf:
    documentclass: scrreprt
---

5.3 ✨ Ajouter une Bibliographie

Pour un document académique ou technique, une bibliographie est essentielle.

  1. Créez un fichier references.bib avec vos citations au format BibTeX.
  2. Ajoutez la clé bibliography: references.bib à votre en-tête YAML.
  3. Citez vos sources dans le texte avec la syntaxe [@auteur_annee].

Exemple : Quarto a été développé par Posit, anciennement RStudio [@allaire_quarto_2022].

6 Conclusion

Vous avez maintenant toutes les clés en main pour commencer à créer des documents riches et reproductibles avec Quarto. De la simple analyse aux rapports complexes, Quarto s’adapte à vos besoins et vous permet de vous concentrer sur l’essentiel : vos données et votre message.

Atelier Pratique : Créez votre premier rapport
  1. Créez un nouveau fichier .qmd et son en-tête YAML (titre, auteur, format html).
  2. Écrivez une introduction expliquant que vous allez analyser le jeu de données penguins.
  3. Ajoutez un bloc de code qui charge le jeu de données penguins de Seaborn et affiche les 5 premières lignes. Cachez le code de ce bloc (echo: false).
  4. ✨ Dans une phrase, utilisez du code en ligne pour indiquer le nombre total de manchots dans le jeu de données.
  5. Créez un nuage de points de la longueur des nageoires (flipper_length_mm) en fonction de la masse corporelle (body_mass_g). Ajoutez une légende et une étiquette (label) au graphique.
  6. Utilisez un callout pour résumer ce que la Figure @votre-etiquette montre.
  7. Rendez le document en utilisant la méthode de votre choix et admirez votre rapport dynamique!
Retour au sommet