العرض

يصف هذا المستند كيفية عرض ملفات التمارين والمسارات المختلفة على الطالب، مع مراعاة ما إذا كان الطالب يستخدم واجهة سطر الأوامر أم المحرّر.

التوثيق

هناك ثلاثة أنواع من التوثيق تحدد ما يُعرض من توثيق للتمرين.

الملفات الخاصة بالتمرين

هذه الملفات خاصة بكل تمرين:

• .docs/introduction.md: يقدّم المفهوم أو المفاهيم التي يعلّمها التمرين للطالب (مطلوب)
• .docs/introduction.append.md: نص مقدمة إضافي يُلحق بعد المقدمة الموجودة (لا يُستخدم في تمارين المفاهيم، واختياري في التمارين التطبيقية)
• .docs/instructions.md: يوفّر تعليمات التمرين (مطلوب)
• .docs/instructions.append.md: نص مقدمة إضافي يُلحق بعد التعليمات الموجودة (لا يُستخدم في تمارين المفاهيم، واختياري في التمارين التطبيقية)
• .docs/hints.md: يوفّر تلميحات للطالب تساعده على تجاوز العقبات في التمرين (مطلوب في تمارين المفاهيم، واختياري في التمارين التطبيقية)
• .meta/config.json: يحتوي على معلومات مصدر التمرين (اختياري)

راجع توثيق تمارين المفاهيم وتوثيق التمارين التطبيقية لمزيد من المعلومات.

الملفات الخاصة بالمسار

هذه الملفات مشتركة بين جميع التمارين:

• debug.md: يشرح كيف يمكن لطالب يكتب الكود في المتصفح أن يقوم بـ «debugging» (اختياري)
• help.md: يحتوي على تعليمات خاصة بالمسار حول كيفية الحصول على المساعدة (مطلوب)
• representations.md: يشرح عمليات التطبيع التي تُطبَّق على الحل لإنشاء تمثيله (اختياري)
• tests.md: يحتوي على تعليمات خاصة بالمسار حول كيفية تشغيل الاختبارات (مطلوب)

راجع توثيق الملفات المشتركة لمزيد من المعلومات.

التوثيق العام على Exercism

إلى جانب ملفات التوثيق الخاصة بالمسار أو التمرين المذكورة أعلاه، هناك جزآن من التوثيق عامّان على Exercism (وبالتالي مشتركان بين جميع المسارات):

• تعليمات حول كيفية استخدام واجهة سطر الأوامر لإرسال تمرين
• تعليمات حول كيفية الحصول على المساعدة

المحرّر

عند العمل على تمرين في المتصفح، تظهر ملفات التوثيق في الأوقات المناسبة. على سبيل المثال، لا تظهر التلميحات إلا إذا طلب الطالب عرضها. ولا يحتاج المحرّر أيضًا إلى عرض تعليمات واجهة سطر الأوامر.

واجهة سطر الأوامر

عند العمل محليًا عبر واجهة سطر الأوامر، لا تتوفر لدينا إمكانية عرض التوثيق بشكل مشروط. لذلك يجب على واجهة سطر الأوامر أن تنزّل دائمًا كل التوثيق ذي الصلة. ولكي لا نضطر الطالب إلى فتح عدة ملفات، تدمج واجهة سطر الأوامر كل التوثيق ذي الصلة في ثلاثة مستندات:

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.