展示

本文档介绍各种练习文件和轨道文件是如何呈现给学生的，并会考虑到学生使用的是 CLI 还是编辑器。

文档

有三种类型的文档决定了一个练习会呈现哪些文档。

练习专属文件

这些文件是每个练习专属的：

  • .docs/introduction.md：向学生介绍该练习所教授的概念（必需）
  • .docs/introduction.append.md：追加在现有引言之后的补充引言文本（概念练习不使用，实践练习可选）
  • .docs/instructions.md：提供练习的说明（必需）
  • .docs/instructions.append.md：追加在现有说明之后的补充文本（概念练习不使用，实践练习可选）
  • .docs/hints.md：提供提示，帮助学生在练习中自己找到出路（概念练习必需，实践练习可选）
  • .meta/config.json：包含练习的来源信息（可选）

更多信息请参阅概念练习文档和实践练习文档。

轨道专属文件

这些文件为所有练习共享：

  • debug.md：说明在浏览器中编写代码的学生如何仍然可以进行“调试”（可选）
  • help.md：包含轨道专属的获取帮助说明（必需）
  • representations.md：说明对解答应用了哪些规范化以生成其表示形式（可选）
  • tests.md：包含轨道专属的运行测试说明（必需）

更多信息请参阅共享文件文档。

Exercism 全局文档

除上述轨道专属或练习专属的文档文件外，还有两段文档是 Exercism 全局的（因此为所有轨道共享）：

  • 如何使用 CLI 提交练习的说明
  • 如何获取帮助的说明

编辑器

在浏览器中做练习时，文档文件会在合适的时机显示。例如，除非学生主动请求，否则不会显示提示。编辑器也无需显示 CLI 说明。

CLI

通过 CLI 在本地工作时，我们无法有条件地显示文档。因此，CLI 必须始终下载所有相关文档。为了不让学生打开多个文件，CLI 会把所有相关文档拼接成三个文档：

README.md

该文件包含练习的说明、引言（可选）和来源信息（可选）。

# [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

该文件说明如何运行测试，以及轨道专属和 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

该文件包含练习专属的提示（可选）

# Hints

## General

- Consider extracting the logic to a helper function.