Certains fichiers de documentation s'appliquent à la fois aux exercices d'apprentissage et aux exercices d'entraînement. Ces fichiers transverses aux exercices se trouvent dans le répertoire exercises/shared/.docs du parcours :
-
debug.md : explique comment un apprenant qui code dans le navigateur peut malgré tout faire du « débogage » (facultatif)
-
help.md : contient les instructions propres au parcours pour obtenir de l'aide (obligatoire)
-
representations.md : explique quelles normalisations sont appliquées à une solution pour créer sa représentation (facultatif)
-
tests.md : contient les instructions propres au parcours pour exécuter les tests (obligatoire)
Le document de présentation décrit comment ces fichiers servent à présenter le contenu à l'apprenant.
Fichier : debug.md
Objectif : Expliquer comment un apprenant qui code dans le navigateur peut malgré tout faire du « débogage »
Présence : Facultatif
L'éditeur intégré au navigateur n'offre aucune prise en charge du débogage. Si l'exécuteur de tests du parcours prend en charge la capture de la sortie console, l'apprenant peut malgré tout faire une forme de « débogage », et ce document explique comment s'y prendre.
Le contenu de ce fichier n'est affiché que dans l'éditeur en ligne ; la CLI l'ignore.
Exemple
# Debug
To help with debugging, you can use the fact that any [console output](https://www.programiz.com/csharp-programming/basic-input-output) will be shown in the test results window. You can write to the console using:
```csharp
Console.WriteLine("Debug message");
```
Fichier : help.md
Objectif : Expliquer comment un apprenant peut obtenir de l'aide
Présence : Obligatoire
Décris comment un apprenant peut obtenir de l'aide, spécifiquement pour ce parcours (et non pour l'ensemble d'Exercism).
Le contenu de ce fichier n'est que utilisé par la CLI, qui l'inclut dans le fichier HELP.md.
Les instructions doivent être courtes et aller droit au but.
Tu peux renvoyer vers des ressources comme des canaux Gitter, des forums ou des listes de diffusion : tout ce qui peut aider un apprenant à se débloquer.
Les liens de ce document peuvent recouper ceux de docs/LEARNING.md ou de docs/RESOURCES.md.
Ce document ne doit pas renvoyer vers des ressources d'aide communes à tout Exercism (indépendantes du parcours), car ces ressources sont automatiquement incluses dans le fichier HELP.md.
Exemple
# Help
To get help if you're having trouble, you can use one of the following resources:
- [Kotlin Documentation](https://kotlinlang.org/docs/reference/)
- [Kotlin Forums](https://discuss.kotlinlang.org/)
- [Kotlin Slack Channel](https://kotlinlang.slack.com/): [get invite here](https://slack.kotlinlang.org/)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/kotlin)
- [Kotlin Subreddit](https://www.reddit.com/r/kotlin)
Fichier : representations.md
Objectif : Expliquer quelles normalisations sont appliquées à une solution pour créer sa représentation
Présence : Facultatif
Quand un parcours a implémenté un representer, une représentation est créée pour chaque solution soumise.
Ce document doit lister toutes les normalisations que le representer applique à une solution.
Cela aide un mentor lorsqu'il ajoute des commentaires de représentation.
Exemple
# Representations
The representer applies the following normalizations:
- All comments are removed
- All import declarations are removed
- The code is formatted
- Identifiers are normalized to a placeholder value
Si ton parcours possède un fichier docs/REPRESENTER_NORMALIZATIONS.md, nous te recommandons de faire pointer les normalisations vers la section correspondante de ce fichier.
Fichier : tests.md
Objectif : Contenir les instructions propres au parcours pour exécuter les tests
Présence : Obligatoire
Décris comment exécuter les tests pour cet exercice en particulier.
Le contenu de ce fichier n'est que utilisé par la CLI, qui l'inclut dans le fichier HELP.md.
Les instructions doivent être courtes et aller droit au but.
Le fichier docs/TESTS.md peut contenir une description plus détaillée de la façon d'exécuter les tests.
Exemple
# Tests
To run the tests, run the command `dotnet test` from within the exercise directory.
Écrasement
Remarque : ceci n'est pas encore implémenté
Les exercices peuvent écraser les fichiers propres au parcours en créant un fichier du même nom dans le répertoire .docs de l'exercice (par exemple .docs/debug.md). Cela ne devrait être nécessaire que rarement (voire jamais).
