4  Callouts et blocs de code

Les callouts permettent de mettre en évidence des informations importantes. Les blocs de code permettent d’afficher ou d’exécuter du code. Ce chapitre les présente tous avec des exemples tirés du contexte doctoral.

4.1 Les cinq types de callouts

Quarto définit cinq types de callouts, chacun avec une sémantique précise :

::: {.callout-specification}
## Titre (optionnel) du callout
Contenu du callout, avec `specification` qui peut prendre les valeurs 
`note`, `tip`, `warning`, `important`, ou `caution`, chacun étant associé à
un code couleur et une icône en entête du bloc de callout. 
:::

4.1.1 callout-note — information neutre

::: {.callout-note}
## Composition du jury

Le jury d'une thèse Cnam comprend au minimum un président, deux rapporteurs
(ayant l'hdr) et un ou deux examinateurs. La soutenance dure environ
45 minutes de présentation, suivies des questions du jury.
:::

Rendu :

NoteComposition du jury

Le jury d’une thèse Cnam comprend au minimum un président, deux rapporteurs (ayant l’hdr) et un ou deux examinateurs. La soutenance dure environ 45 minutes de présentation, suivies des questions du jury.

4.1.2 callout-tip — conseil actionnable

::: {.callout-tip}
## Commencez à rédiger tôt

Commencez à rédiger votre thèse dès la deuxième année de doctorat. La rédaction
tardive est la première cause de dépassement de la durée contractuelle de thèse.
Même des ébauches imparfaites valent mieux que des sections vides.
:::

Rendu :

AstuceCommencez à rédiger tôt

Commencez à rédiger votre thèse dès la deuxième année de doctorat. La rédaction tardive est la première cause de dépassement de la durée contractuelle de thèse. Même des ébauches imparfaites valent mieux que des sections vides.

4.1.3 callout-warning — piège à éviter

::: {.callout-warning}
## Ne renommez pas les chapitres sans mettre à jour le profil

Si vous renommez un fichier `.qmd`, mettez à jour la liste `chapters:` dans
`_quarto-fr.yml` (ou `_quarto-en.yml`). Quarto ne détecte pas automatiquement
les fichiers manquants et échouera silencieusement.
:::

Rendu :

AvertissementNe renommez pas les chapitres sans mettre à jour le profil

Si vous renommez un fichier .qmd, mettez à jour la liste chapters: dans _quarto-fr.yml (ou _quarto-en.yml). Quarto ne détecte pas automatiquement les fichiers manquants et échouera silencieusement.

4.1.4 callout-important — point non négociable

::: {.callout-important}
## PDF/A-1b obligatoire pour theses.fr

L'abes exige un PDF/A pour l'archivage sur theses.fr. Ce template
génère automatiquement un PDF/A-1b via `\usepackage[a-1b]{pdfx}`. Ne retirez pas
ce package du template.
:::

Rendu :

ImportantPDF/A-1b obligatoire pour theses.fr

L’abes exige un PDF/A pour l’archivage sur theses.fr. Ce template génère automatiquement un PDF/A-1b via \usepackage[a-1b]{pdfx}. Ne retirez pas ce package du template.

4.1.5 callout-caution — danger avec conséquences

::: {.callout-caution}
## N'utilisez pas `date:` pour la date de soutenance

Quarto interprète la clé `date:` comme une date JavaScript et produit
« Invalid Date » pour les dates françaises (ex. « 12 juin 2026 »). Utilisez
exclusivement la clé personnalisée `date-soutenance:` prévue dans ce template.
:::

Rendu :

Mise en gardeN’utilisez pas date: pour la date de soutenance

Quarto interprète la clé date: comme une date JavaScript et produit « Invalid Date » pour les dates françaises (ex. « 12 juin 2026 »). Utilisez exclusivement la clé personnalisée date-soutenance: prévue dans ce template.

4.2 Callouts avec titre et repliement

Le titre s’ajoute avec une ligne ## Titre à l’intérieur du callout (comme dans les exemples ci-dessus). Pour rendre un callout replié par défaut (cliquable pour l’ouvrir), on utilise l’attribut collapse :

::: {.callout-tip collapse="true"}
## Cliquer pour voir le conseil (replié par défaut)

Ce callout est replié à l'ouverture du document HTML. En PDF, il s'affiche
toujours en entier (le repliement est une fonctionnalité HTML uniquement).
:::

Rendu :

Ce callout est replié à l’ouverture du document HTML. En PDF, il s’affiche toujours en entier (le repliement est une fonctionnalité HTML uniquement).

4.3 Blocs de code — affichage seul

Pour afficher du code sans l’exécuter, on utilise soit un bloc délimité par des backticks sans spécificateur de langage entre accolades, soit un chunk avec eval: false :

```python
# Ce bloc est affiché mais non exécuté
import numpy as np
x = np.linspace(0, 10, 100)
print(x.mean())
```

Rendu :

# Ce bloc est affiché mais non exécuté
import numpy as np
x = np.linspace(0, 10, 100)
print(x.mean())

Pour afficher le code d’un chunk exécutable sans l’exécuter (utile pour des exemples d’installation ou de configuration) :

```{python}
#| eval: false
#| echo: true
# Installation des dépendances
pip install matplotlib numpy pandas
```

Rendu :

# Installation des dépendances du template
# pip install matplotlib numpy pandas
AstuceOptions de chunk les plus utiles
Table 4.1: Options de chunk Quarto fréquemment utilisées.
Option Valeurs Effet
echo true/false affiche ou masque le code
eval true/false exécute ou non le code
output true/false affiche ou masque la sortie
warning true/false affiche ou masque les avertissements
fig-cap texte légende de la figure produite
label fig-... ou tbl-... identifiant pour cross-référence

4.4 Blocs de code — avec exécution Python

Dans ce document, tous les exemples de code exécutable — y compris les figures matplotlib du Section 2.2 — utilisent #| echo: true pour afficher à la fois le code source et le résultat. Dans une thèse finalisée, on masque généralement le code en passant #| echo: false : seule la figure ou le tableau apparaît, sans le code qui l’a produit.

NoteLangages pris en charge nativement par Quarto

Quarto prend en charge trois langages de calcul scientifique sans configuration supplémentaire : Python, R et Julia. La syntaxe des options de chunk (#| echo:, #| fig-cap:, etc.) et le mécanisme de cross-référence (#| label:) sont identiques pour les trois langages. Ce document n’illustre que Python.

Documentation officielle :

Un chunk Python avec eval: true (valeur par défaut) exécute le code et affiche la sortie. Voici un exemple avec pandas :

```{python}
#| echo: true
#| label: tbl-pandas
#| tbl-cap: "Statistiques descriptives des fonctions trigonométriques."
import numpy as np, pandas as pd
from IPython.display import Markdown

x = np.linspace(0, 2 * np.pi, 1000)
df = pd.DataFrame({r'$\sin(x)$':           np.sin(x),
                   r'$\cos(x)$':           np.cos(x),
                   r'$\tan(x)$ (tronqué)': np.clip(np.tan(x), -5, 5)})
Markdown(df.describe().round(3).to_markdown())
```

Rendu :

import numpy as np, pandas as pd
from IPython.display import Markdown

x = np.linspace(0, 2 * np.pi, 1000)
df = pd.DataFrame({r'$\sin(x)$':           np.sin(x),
                   r'$\cos(x)$':           np.cos(x),
                   r'$\tan(x)$ (tronqué)': np.clip(np.tan(x), -5, 5)})
Markdown(df.describe().round(3).to_markdown())
Table 4.2: Statistiques descriptives des fonctions trigonométriques.
\sin(x) \cos(x) \tan(x) (tronqué)
count 1000 1000 1000
mean 0 0.001 -0
std 0.707 0.708 2.335
min -1 -1 -5
25% -0.706 -0.705 -0.997
50% -0 0.002 -0
75% 0.706 0.708 0.997
max 1 1 5
Notefreeze: auto dans _quarto.yml

Avec execute: freeze: auto, Quarto stocke les résultats des cellules dans _freeze/ et ne les recalcule que si le code du chunk a changé. Cela accélère considérablement les rendus successifs pour les thèses avec beaucoup de calculs.

Mise en gardePensez à versionner le dossier _freeze/

Si vous versionnez votre thèse sur GitHub et souhaitez que les relecteurs puissent compiler sans Python installé, committez le dossier _freeze/. Les résultats mis en cache y sont stockés et seront utilisés à la place de l’exécution.