Présentation

Ce document décrit comment les différents fichiers d'exercice et de parcours sont présentés à l'apprenant, selon que celui-ci utilise la CLI ou l'éditeur.

Documentation

Il existe trois types de documentation qui déterminent la documentation présentée pour un exercice.

Fichiers propres à l'exercice

Ces fichiers sont propres à chaque exercice :

  • .docs/introduction.md : présente le ou les concepts que l'exercice enseigne à l'apprenant (obligatoire)
  • .docs/introduction.append.md : texte d'introduction supplémentaire à ajouter après l'introduction existante (non utilisé dans les exercices d'apprentissage, facultatif pour les exercices d'entraînement)
  • .docs/instructions.md : fournit les instructions de l'exercice (obligatoire)
  • .docs/instructions.append.md : texte d'instructions supplémentaire à ajouter après les instructions existantes (non utilisé dans les exercices d'apprentissage, facultatif pour les exercices d'entraînement)
  • .docs/hints.md : fournit des indices à l'apprenant pour l'aider à se débloquer dans un exercice (obligatoire pour les exercices d'apprentissage, facultatif pour les exercices d'entraînement)
  • .meta/config.json : contient les informations de source de l'exercice (facultatif)

Consulte la documentation sur les exercices d'apprentissage et la documentation sur les exercices d'entraînement pour plus d'informations.

Fichiers propres au parcours

Ces fichiers sont partagés entre tous les exercices :

  • debug.md : explique comment un apprenant qui code dans le navigateur peut tout de même 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)

Consulte la documentation sur les fichiers partagés pour plus d'informations.

Documentation commune à Exercism

En plus des fichiers de documentation ci-dessus, propres au parcours ou à l'exercice, il existe deux éléments de documentation communs à Exercism (et donc partagés entre tous les parcours) :

  • Les instructions sur l'utilisation de la CLI pour soumettre un exercice
  • Les instructions pour obtenir de l'aide

Éditeur

Lorsqu'on travaille sur un exercice dans le navigateur, les fichiers de documentation s'affichent au moment opportun. Par exemple, les indices ne sont affichés que si l'apprenant demande à les voir. L'éditeur n'a pas non plus besoin d'afficher les instructions de la CLI.

CLI

Lorsqu'on travaille en local via la CLI, on n'a pas la possibilité d'afficher la documentation de manière conditionnelle. La CLI doit donc toujours télécharger toute la documentation pertinente. Pour éviter de demander à l'apprenant d'ouvrir plusieurs fichiers, la CLI concatène toute la documentation pertinente en trois documents :

README.md

Ce fichier contient les instructions de l'exercice, l'introduction (facultative) et les informations de source (facultatives).

# [exercise name]

Welcome to [exercise name] on Exercism's [track name] Track.
If you need help running the tests or submitting your code, check out `HELP.md`.
If you get stuck on the exercise, check out `HINTS.md`, but try and solve it without using those first :)

## Introduction (optional)

[Exercise-specific file: .docs/introduction.md] (optional)

[Exercise-specific file: .docs/introduction.append.md] (optional)

## Instructions

[Exercise-specific file: .docs/instructions.md]

[Exercise-specific file: .docs/instructions.append.md] (optional)

## Source

### Created by

- @[author-1 handle]
- @[author-2 handle]
  ...

### Contributed to by (optional)

- @[contributor-1 handle]
- @[contributor-2 handle]
  ...

### Based on

[source] - [source url]

HELP.md

Ce fichier décrit comment exécuter les tests, ainsi que les instructions d'aide propres au parcours et communes à Exercism.

# Help

## Running the tests

[Track-specific file: exercises/shared/.docs/tests.md]

## Submitting your solution

[Exercism-wide documentation: instructions on how to submit a solution]

## Need to get help?

[Exercism-wide documentation: instructions on how to get help]

[Track-specific file: exercises/shared/.docs/help.md]

HINTS.md

Ce fichier contient les indices propres à l'exercice (facultatifs)

# Hints

## General

- Consider extracting the logic to a helper function.