Este documento descreve como os vários arquivos de exercício e de trilha são apresentados ao estudante, levando em conta se está usando a CLI ou o editor.
Documentação
Existem três tipos de documentação que determinam qual documentação é apresentada para um exercício.
Arquivos específicos do exercício
Esses arquivos são específicos de cada exercício:
-
.docs/introduction.md: apresentam o(s) conceito(s) que o exercício ensina ao estudante (obrigatório)
-
.docs/introduction.append.md: texto de introdução adicional para acrescentar depois da introdução existente (não é usado em exercícios de conceito, opcional em exercícios de prática)
-
.docs/instructions.md: fornecem as instruções do exercício (obrigatório)
-
.docs/instructions.append.md: texto de introdução adicional para acrescentar depois das instruções existentes (não é usado em exercícios de conceito, opcional em exercícios de prática)
-
.docs/hints.md: fornecem dicas para ajudar o estudante a se destravar em um exercício (obrigatório em exercícios de conceito, opcional em exercícios de prática)
-
.meta/config.json: contém as informações de origem do exercício (opcional)
Consulte a documentação dos Exercícios de Conceito e a documentação dos Exercícios de Prática para mais informações.
Arquivos específicos da trilha
Esses arquivos são compartilhados entre todos os exercícios:
-
debug.md: explica como um estudante que programa no navegador ainda pode fazer "debug" (opcional)
-
help.md: contém instruções específicas da trilha sobre como conseguir ajuda (obrigatório)
-
representations.md: explica quais normalizações são aplicadas a uma solução para criar sua representação (opcional)
-
tests.md: contém instruções específicas da trilha sobre como rodar os testes (obrigatório)
Consulte a documentação dos arquivos compartilhados para mais informações.
Documentação geral do Exercism
Além dos arquivos de documentação específicos de trilha ou de exercício acima, há dois trechos de documentação que são gerais do Exercism (e, portanto, compartilhados por todas as trilhas):
- Instruções sobre como usar a CLI para enviar um exercício
- Instruções sobre como conseguir ajuda
Editor
Ao trabalhar em um exercício no navegador, os arquivos de documentação aparecem nos momentos relevantes. Por exemplo, as dicas não são exibidas a menos que o estudante peça para exibi-las. O editor também não precisa exibir as instruções da CLI.
CLI
Ao trabalhar localmente pela CLI, não temos a opção de exibir a documentação condicionalmente. Por isso, a CLI precisa sempre baixar toda a documentação relevante. Para que o estudante não precise abrir vários arquivos, a CLI concatena toda a documentação relevante em três documentos:
README.md
Este arquivo contém as instruções do exercício, a introdução (opcional) e as informações de origem (opcional).
# [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
Este arquivo descreve como rodar os testes, além das instruções de ajuda específicas da trilha e gerais do 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
Este arquivo contém as dicas específicas do exercício (opcional)
# Hints
## General
- Consider extracting the logic to a helper function.
