mdBook : insérer un code Rust modifiable et exécutable

LA raison principale pour laquelle la communauté Rust s’est dotée de mdBook, c’est la capacité à gérer ce que comporte ce chapitre.

Nous avons vu comme insérer un contenu de fichier .md dans un autre fichier .md avec la consigne {{#include}}.

Il est également possible d’insérer le contenu d’un fichier de code source Rust (dont le nom se termine généralement par .rs) dans un fichier .md avec cette même consigne, sous réserve d’insérer la consigne dans un bloc code Rust.

Ainsi,

```rust
{{#include ./codes-rust/helloworld.rs}}
```

affiche le bloc de code :

fn main () {
	println!("Hello world!");
}

qui est le contenu du fichier « codes-rust/helloworld.rs » que nous avons préalablement créé.

Traitement par défaut

Si nous ne faisons rien de particulier, le bloc de code Rust propose une option Run this code (exécuter ce code) avec un bouton associé.

En effet, le script fait un lien avec le « Playground » (« espace de jeu » ou « terrain de jeu ») de Rust qui permet de tester des codes Rust et qui :

• les compile ;
• les exécute si la compilation réussit.

Le playground Rust complet est accessible en mode Web à cette adresse : https://play.rust-lang.org/.

Rendre le code Rust modifiable

Nous pouvons donner la possibilité aux lecteurs de modifier le code directement dans notre livre web et de l’exécuter.

Il nous faut tout d’abord indiquer cela dans le fichier de paramètres du compilateur, /nom-du-projet/book.toml, en ajoutant la ligne playground.editable = true dans la section [output.html] :

[output.html]
playground.editable = true

Ensuite, nous indiquons l’option sur chaque bloc de code pour lequel nous souhaitons activer la fonctionnalité avec le mot clef editable (= modifiable, ou éditable) :

```rust,editable
{{#include ./codes-rust/helloworld.rs}}
```

Ce qui produit :

fn main () {
	println!("Hello world!"
// Ce code ne passe pas en compilation.
// Vous pouvez le corriger ou simplement
// modifier ce commentaire pour tester
// la fonction « edit » si vous voulez.
}

Le lecteur peut intervenir dans le code du bloc de code ci-avant et dispose maintenant d’un bouton Undo changes (= annuler les modifications) supplémentaire pour revenir à la version proposée au départ par la page mdBook.

Annihiler la possibilité d’exécuter le code

À l’inverse, nous pouvons limiter le bloc de code Rust pour ne proposer que l’affichage et la copie du code.

```rust,ignore
{{#include ./codes-rust/helloworld.rs}}
```

affiche :

fn main () {
	println!("Hello world!");
}

Le bouton Run this code n’est alors plus affiché.

Les dossiers et fichiers de codes Rust sont conservés dans le projet Web

Si nous créons des fichiers de codes Rust, le compilateur les copie dans le dossier book/.

Si nous avons pris soin de créer un dossier spécifique comme je l’ai fait ici (codes-rust/), le dossier existe dans le projet cible et les fichiers sources y sont disponibles.

Par exemple ici : dossier des fichiers de code Rust (dont l’accès vous est interdit par mon serveur nginx, mais je pourrais ouvrir l’accès au parcours de ce dossier si c’était utile).

Nous pouvons également proposer des liens vers un fichier particulier par exemple : fichier de code Rust (ce coup-ci, votre navigateur devrait télécharger le fichier si vous cliquez sur le lien).

Écrire les sources directement dans le fichier .md

Bien entendu, cela fonctionne sans insérer un fichier, et nous pouvons utiliser ces mêmes options pour un code Rust que nous saisissons directement dans le fichier .md.

La rigueur d’un développeur veut que l’on écrive généralement les fichiers .rs à part et qu’on les insère dans le projet comme lorsque nous réalisons des programmes.

Nous pouvons toutefois tout à fait écrire directement dans un fichier .md :

```rust,editable
fn main () {
	println!("Hello world!"
// Ce code ne passe pas en compilation.
// Vous pouvez le corriger ou simplement
// modifier ce commentaire pour tester
// la fonction « edit » si vous voulez.
}
```

qui produira :

fn main () {
	println!("Hello world!"
// Ce code ne passe pas en compilation.
// Vous pouvez le corriger ou simplement
// modifier ce commentaire pour tester
// la fonction « edit » si vous voulez.
}

Ceci n’est qu’un aperçu

Ceci n’est qu’un aperçu des options offertes par le langage mdBook pour tester et afficher des codes Rust.