Ce bloc-notes mdBook vous est proposé avec passion par Marc JESTIN — Happy Numeric.
À votre service pour vous accompagner dans vos projets numériques.
Contact : https://happynumeric.fr/me-contacter.
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 (Markdown) dans un autre fichier .md (Markdown) avec la consigne {{ #include }}
.
Il est également possible d'insérer le contenu d'un fichier .rs (code Rust) dans un fichier .md (MarkDown) 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 » (« 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 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 les lignes :
[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 le document 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 pas 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 .rs y sont disponibles.
Par exemple ici : dossier des fichiers de code Rust.
Nous pouvons également proposer des liens vers un fichier particulier par exemple : fichier de code Rust non modifiable
Cela fonctionne sans insérer un fichier .rs
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 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 des possibilités
Ceci n'est qu'un aperçu des options offertes par le langage mdBook pour tester et afficher des codes Rust.
Ce bloc-notes mdBook vous est proposé par Marc JESTIN — Happy Numeric. |
Formation, rédaction de documentations techniques ou organisationnelles, mise en place de solutions documentaires internes et externes, assistance à maîtrise d'ouvrage, etc. |
Contact : https://happynumeric.fr/me-contacter |
N'hésitez pas à me faire votre feedback, me signaler des erreurs ou des compléments que vous souhaiteriez que j'ajoute à ce bloc-notes mdBook.
Cliquez ici pour me contacter
Versions de cette page
Création : 19 mars 2023
Dernière mise à jour : 19 mars 2023 17:09