Ez a dokumentum leírja, hogyan jelennek meg a különféle feladat- és kurzusfájlok a tanulónak, figyelembe véve, hogy a tanuló a CLI-t vagy a szerkesztőt használja.
Dokumentáció
Háromféle dokumentáció határozza meg, hogy milyen dokumentáció jelenik meg egy feladatnál.
Feladatspecifikus fájlok
Ezek a fájlok feladatonként egyediek:
-
.docs/introduction.md: bemutatja a feladat által tanított fogalmat vagy fogalmakat a tanulónak (kötelező)
-
.docs/introduction.append.md: kiegészítő bevezető szöveg, amely a meglévő bevezetés után fűződik hozzá (tanulófeladatoknál nem használatos, gyakorlófeladatoknál opcionális)
-
.docs/instructions.md: utasításokat tartalmaz a feladathoz (kötelező)
-
.docs/instructions.append.md: kiegészítő bevezető szöveg, amely a meglévő utasítások után fűződik hozzá (tanulófeladatoknál nem használatos, gyakorlófeladatoknál opcionális)
-
.docs/hints.md: tippeket ad a tanulónak, hogy segítsen neki, ha elakad egy feladatban (tanulófeladatoknál kötelező, gyakorlófeladatoknál opcionális)
-
.meta/config.json: a feladat forrásinformációit tartalmazza (opcionális)
További információért lásd a tanulófeladatok dokumentációját és a gyakorlófeladatok dokumentációját.
Kurzusspecifikus fájlok
Ezek a fájlok minden feladatban közösek:
-
debug.md: elmagyarázza, hogyan tud egy böngészőben kódoló tanuló is „debugolni” (opcionális)
-
help.md: kurzusspecifikus utasításokat tartalmaz arról, hogyan kérhetsz segítséget (kötelező)
-
representations.md: elmagyarázza, milyen normalizálásokat alkalmazunk egy megoldásra a reprezentációja létrehozásához (opcionális)
-
tests.md: kurzusspecifikus utasításokat tartalmaz a tesztek futtatásáról (kötelező)
További információért lásd a megosztott fájlok dokumentációját.
Exercism-szintű dokumentáció
A fenti, kurzushoz vagy feladathoz tartozó dokumentációs fájlokon kívül két dokumentációs elem van, amely Exercism-szintű (és ezért minden kurzusban közös):
- Utasítások arról, hogyan küldhetsz be egy feladatot a CLI-vel
- Utasítások arról, hogyan kérhetsz segítséget
Szerkesztő
Amikor a böngészőben dolgozol egy feladaton, a dokumentációs fájlok a megfelelő időpontokban jelennek meg. Például a tippek nem jelennek meg, hacsak a tanuló nem kéri, hogy megjelenjenek. A szerkesztőnek emellett nem kell megjelenítenie a CLI utasításait sem.
CLI
Amikor a CLI-n keresztül helyben dolgozol, nincs lehetőségünk a dokumentáció feltételes megjelenítésére. Ezért a CLI-nek mindig le kell töltenie az összes releváns dokumentációt. Hogy a tanulónak ne kelljen több fájlt megnyitnia, a CLI az összes releváns dokumentációt három dokumentumba fűzi össze:
README.md
Ez a fájl a feladat utasításait, bevezetését (opcionális) és forrásinformációit (opcionális) tartalmazza.
# [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
Ez a fájl leírja, hogyan futtathatod a teszteket, valamint a kurzus- és Exercism-szintű segítségnyújtási utasításokat.
# 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
Ez a fájl a feladatspecifikus tippeket tartalmazza (opcionális)
# Hints
## General
- Consider extracting the logic to a helper function.
