Apresentação

Este documento descreve como os vários ficheiros de exercícios e de percursos são apresentados ao estudante, tendo em conta se o estudante está a usar a CLI ou o editor.

Documentação

Há três tipos de documentação que determinam que documentação é apresentada para um exercício.

Ficheiros específicos do exercício

Estes ficheiros são específicos de cada exercício:

  • .docs/introduction.md: apresenta 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 para exercícios de prática)
  • .docs/instructions.md: fornece 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 para exercícios de prática)
  • .docs/hints.md: fornece dicas ao estudante para o ajudar a desbloquear-se num exercício (obrigatório para exercícios de conceito, opcional para exercícios de prática)
  • .meta/config.json: contém informação sobre a origem do exercício (opcional)

Consulta a documentação dos exercícios de conceito e a documentação dos exercícios de prática para mais informações.

Ficheiros específicos do percurso

Estes ficheiros são partilhados por todos os exercícios:

  • debug.md: explica como um estudante que está a programar no navegador ainda pode fazer "debugging" (opcional)
  • help.md: contém instruções específicas do percurso sobre como obter ajuda (obrigatório)
  • representations.md: explica que normalizações são aplicadas a uma solução para criar a sua representação (opcional)
  • tests.md: contém instruções específicas do percurso sobre como correr os testes (obrigatório)

Consulta a documentação dos ficheiros partilhados para mais informações.

Documentação transversal ao Exercism

Além dos ficheiros de documentação específicos do percurso e do exercício acima referidos, há dois elementos de documentação que são transversais ao Exercism (e, por isso, partilhados por todos os percursos):

  • Instruções sobre como usar a CLI para submeter um exercício
  • Instruções sobre como obter ajuda

Editor

Quando trabalhas num exercício no navegador, os ficheiros de documentação aparecem nos momentos relevantes. Como exemplo, as dicas não são mostradas a menos que o estudante peça para as mostrar. Além disso, o editor também não precisa de mostrar as instruções da CLI.

CLI

Quando trabalhamos localmente através da CLI, não temos a opção de mostrar a documentação de forma condicional. Por isso, a CLI tem de descarregar sempre toda a documentação relevante. Para não obrigar o estudante a abrir vários ficheiros, a CLI concatena toda a documentação relevante em três documentos:

README.md

Este ficheiro contém as instruções, a introdução (opcional) e a informação sobre a origem do exercício (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 ficheiro descreve como correr os testes, bem como as instruções de ajuda específicas do percurso e transversais ao 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 ficheiro contém as dicas específicas do exercício (opcional)

# Hints

## General

- Consider extracting the logic to a helper function.