انتقل إلى المحتوى

دليل أسلوب التوثيق

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

النمط العام

  • يجب أن تكون الحروف الأولى من العناوين والعناوين الرئيسية فقط كبيرة.
  • نفضل استخدام قواعد الإملاء الأمريكية، مع بعض الحرية في استخدام المصطلحات العامية الخاصة بالبرمجة (مثل "apps") وتحويل الأسماء إلى أفعال (مثل "scrollable").
  • تهجئة كلمتي "artefact" و"artefacts" هي كما هو موضح.
  • نستخدم مسافة واحدة بعد النقطة.
  • نستخدم واصلة واحدة محاطة بمسافات كشرطة طويلة (أو حرف HTML — حرفي).
  • يجب أن تستخدم أي إشارة إلى اسم منتج الأحرف الكبيرة المفضلة للمنتج. (على سبيل المثال، "macOS"، "GTK"، "pytest"، "Pygame"، "PyScript").
  • إذا كان المصطلح يستخدم "ككود"، فيجب اقتباسه ككود مضمن، عن طريق وضعه بين علامتي اقتباس مفردة، بدلاً من إضافته إلى القاموس.
  • نتجنب استخدام مصطلحات مثل "ببساطة" أو "فقط" أو "بسهولة" عند وصف الإجراءات التي يجب على المستخدم اتخاذها. يمكن أن تُفهم هذه المصطلحات على أنها مهينة، خاصةً عندما يواجه المستخدم صعوبات.

المعلومات المرجعية

يجب عليك إجراء مراجعة مرجعية للمحتوى في الوثائق كلما أمكن ذلك. يغطي هذا القسم الطرق المختلفة التي يمكنك من خلالها القيام بذلك، والتي تعتمد كل منها على نوع المعلومات المرجعية.

يقوم MkDocs بعرض الروابط المنسقة بتنسيق Markdown القياسي. فيما يلي الروابط التشعبية على الويب المنسقة بتنسيق Markdown القياسي:

[Link text](https://example.com/)

يمكنك أيضًا استخدام هذا التنسيق للربط بملف محلي:

[Link text](path/to/file.md)

للإشارة إلى أقسام محددة من الملفات أو وثائق API، يجب استخدام تنسيق رابط مرجع MkDocs.

مرساة Markdown مخصصة وإحالة مرجعية للمحتوى

يُنشئ Markdown روابط لجميع العناوين (أي شيء في سطر واحد يبدأ برمز واحد إلى ستة رموز #)، بناءً على محتوى العنوان. على سبيل المثال، الرابط الذي تم إنشاؤه لهذا القسم هو custom-markdown-anchors-and-content-cross—referencing. ومع ذلك، نظرًا لطريقة عمل ترجماتنا، في أي وقت يتم الرجوع إلى عنوان قسم، يجب أن يكون له رابط مخصص.

يدعم MkDocs عرض صيغة ارتباط مرجعي تسمح لك بالارتباط بالعديد من العناصر الأخرى في الوثائق باستخدام ارتباط Markdown معدل. ويشمل ذلك الارتباط، من بين أمور أخرى، برؤوس Markdown المخصصة ومثبتات النص.

روابط مرجعية MkDocs هي أي روابط منسقة على النحو التالي:

[Link text][link-target]

يلزم وجود عناوين مخصصة ومحتويات مرجعية

أي عنوان أو قسم محتوى يتم الإشارة إليه في محتوى نصي عبر رابط مرجعي MkDocs في وثائق BeeWare يجب أن يكون مرفقًا به رابط مخصص. وإلا، فهناك احتمال لكسر الروابط عند ترجمة محتوى العنوان.

إذا كنت بحاجة إلى الارتباط بمرساة رأس الصفحة، فستحتاج إلى إنشاء مرساة مخصصة للمحتوى المقصود. الصيغة العامة لتعيين مرساة مخصصة هي كما يلي:

# Header text { #anchor-name }

على سبيل المثال، يمكن تخصيص الرابط لهذا القسم إلى custom-anchors باستخدام التنسيق التالي:

## Custom Markdown anchors { #custom-anchors }

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

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

بمجرد إنشاء المراسي المخصصة، يمكنك الارتباط بها من داخل نفس المستند أو في أجزاء أخرى من الوثائق.

يستخدم Standard Markdown للربط بمرساة في نفس الملف، والتي يتم تنسيقها على النحو التالي:

[Link text](#anchor-name)

يستخدم الارتباط بمرساة في مستند منفصل نمط ارتباط مرجعي MkDocs، والذي يتم تنسيقه على النحو التالي:

[Link text][anchor-name]

روابط مرجعية API

تدعم روابط مرجعية MkDocs أيضًا الإحالات المرجعية لوثائق واجهة برمجة التطبيقات (API)، بما في ذلك الفئات الموثقة وأساليب أو سمات الفئات، والإحالات المرجعية للوثائق الخارجية المحددة.

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

يتم تنسيق الارتباط بفئة أثناء عرض مساحة الاسم على النحو التالي:

[`module.ClassName`][]

يتم تنسيق الارتباط بفصل دراسي مع عرض اسم الفصل فقط على النحو التالي:

[`ClassName`][module.ClassName]

السمات هي نفسها المذكورة أعلاه، مع تضمين اسم السمة. فيما يلي عرض لمساحة الاسم:

[`module.ClassName.attributename`][]

كما هو الحال مع الفئات، يتم تنسيق عرض اسم السمة فقط على النحو التالي:

[`attributename`][module.ClassName.attributename]

يجب عرض الطرق مع () بعد مساحة الاسم، وبالتالي يجب التعامل معها بشكل مختلف عن السمات. فيما يلي الطريقة المناسبة للربط بطريقة:

[`module.ClassName.methodname()`][module.ClassName.methodname]

يعرض ما يلي اسم الفئة والطريقة فقط. وهذا يتطلب أيضًا تضمين الأقواس بعد الاسم:

[`Classname.methodname()`][module.Classname.methodname]

يمكنك الارتباط بفئة أو طريقة أو سمة أثناء عرض نص عشوائي، باستخدام نفس الطريقة مع مساحة الاسم القابلة للتطبيق. يتم تنسيق القيام بذلك مع فئة على النحو التالي:

[link text][module.ClassName]

من الممكن أيضًا الارتباط مباشرة بوثائق Python الأساسية، وكذلك وثائق Pillow. على سبيل المثال، للارتباط بوثائق int:

[`int`][]

للربط بوثائق Pillow Image:

[`PIL.Image.Image`][]

نصائح حول كتلة الكود

تسليط الضوء على اللغة والرموز

يمكنك تحديد لغة الكود الموجود داخل كتلة الكود عن طريق إدراج اسم اللغة بعد أول ثلاثة علامات اقتباس مائلة، دون ترك مسافة بينها. ينتج عن ذلك تمييز الكود بشكل مناسب عند عرضه. على سبيل المثال، لتحديد لغة Python، يمكنك بدء كتلة الكود بـ ```python.

أوامر وحدة التحكم وزر النسخ

إذا كنت تضمّن أوامر وحدة التحكم أو أوامر مع مخرجات، فقم بتسميتها بـ "console" أو "doscon"، اعتمادًا على ما إذا كنت تصف نظام تشغيل مشابه لنظام Unix (بما في ذلك macOS) أو Windows. يمكنك تضمين الموجه الذي يوفره نظام التشغيل؛ سيتم نسخ الأمر فقط عند النقر فوق زر النسخ. على سبيل المثال، إذا بدأت كتلة كود بـ "console" وأدرجت المحتوى التالي:

$ mkdir test
$ ls
test

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

تسليط الضوء على أسطر معينة من الكود

يمكنك تمييز أسطر معينة من الكود. على سبيل المثال، لتمييز السطر 2، يمكنك إضافة مسافة بعد اللغة، متبوعة بـ {hl_lines="2"}. وبالتالي، سيبدأ كودك بـ ```python {hl_lines="2"}. والنتيجة هي:

import toga
from toga.style.pack import COLUMN, ROW

يمكنك تمييز عدة أسطر مختلفة. على سبيل المثال، python {hl_lines="3 5 9"} سيميز الأسطر 3 و 5 و 9. يمكنك أيضًا تمييز مجموعة من الأسطر. على سبيل المثال، python {hl_lines="3-8"} يبرز الأسطر من 3 إلى 8. يمكنك تمييز عدة نطاقات، على سبيل المثال، python {hl_lines="9-18 23-44"}.

عناصر التخفيض التي تتطلب تنسيقًا محددًا

نظرًا لطريقة إنشاء ملفات الترجمة، من المهم تضمين الأسطر الجديدة المطلوبة في صيغة Markdown للتنبيهات والملاحظات وعلامات التبويب وتوجيهات Jinja وتعليقات الصور والمحاذاة، إلخ.

تحذيرات وملاحظات

يجب تنسيق التحذيرات على النحو التالي، بما في ذلك التأكد من وجود سطر جديد قبل وبعد بداية التحذير ونهايته:

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

يعمل هذا بنفس الطريقة مع أي نوع من أنواع التحذيرات المدعومة. على سبيل المثال، تتطلب تحذيرات الملاحظات نفس التنسيق وخطوط الأسطر الجديدة:

Content above.

/// note | Note title

Note text here.

///

Content below.

جميع أنواع التحذيرات المدعومة متاحة للاستخدام كإرشادات.

محتوى مبوب

يتم تنسيق المحتوى المبوب على النحو التالي، بما في ذلك إدراج سطر جديد قبل بداية كتلة المحتوى وبعد نهايتها:

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

سيتم تنسيق علامة تبويب تحتوي على تحذير متداخل على النحو التالي، بما في ذلك سطر جديد قبل وبعد كتلة المحتوى:

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

المحتوى المطوي

يتم تنسيق المحتوى المنهار على النحو التالي، بما في ذلك الأسطر الجديدة:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

جميع أنواع التحذيرات المدعومة متاحة للاستخدام مع المحتوى المطوي، ولكن يجب عليك تعريفها على أنها details-admonitiontype. لذا، فإن الكتلة المطوية من نوع "ملاحظة" ستكون details-note (كما هو موضح أعلاه)، والكتلة المطوية من نوع "تحذير" ستكون details-warning، وهكذا.

توجيهات Jinja

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

Content above.



Content below.

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

Content above.

{{ variable }}

Content below.

تنسيق الصور

يمكن ضبط عرض الصور ومحاذاة الصور إلى اليسار واليمين والوسط (مع تحذير بشأن "الوسط"). يجب أن تتضمن الصور دائمًا نصًا بديلًا ذا معنى لأغراض إمكانية الوصول.

يتم تنسيق عرض 300px على الصورة على النحو التالي:

![Image alt text](../path/to/image.png){ width="300px" }

سيتم تنسيق محاذاة الصورة إلى اليسار (أو اليمين) على النحو التالي:

![Image alt text](../path/to/image.png){ align=left }

تتطلب إضافة تعليق إلى صورة إدراج سطر جديد قبله وبعده، ويتم تنسيقه على النحو التالي:

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

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

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

المكونات الإضافية ذات تنسيق Markdown محدد

تتناول الأقسام التالية كيفية استخدام المكونات الإضافية التي تتطلب تنسيق Markdown محددًا.

استخدام المقتطفات لتضمين محتوى خارجي

للحصول على تفاصيل حول كيفية تضمين محتوى خارجي من ملف محلي أو عنوان URL، راجع وثائق ملحق Snippets. يجب استخدام Snippets طالما أن المستند لا يحتوي على توجيهات Jinja التي يجب تنفيذها (يتم تنفيذ Jinja جنبًا إلى جنب مع معالجة Snippets، وبالتالي لن تتم معالجة أي Jinja في الملف). تعد Snippets ضرورية إذا كنت تريد استخدام فواصل تسمح لك بتضمين أجزاء معينة من ملف بشكل منفصل، على سبيل المثال، يتم تقسيم المستند المصدر إلى أقسام ليتم إدراجها بشكل منفصل عن بعضها البعض.

ملاحظات مهمة:

  • نستخدم -8<- كمُعرف للمقتطفات. توضح الوثائق عدة خيارات؛ يرجى اتباع أسلوبنا.
  • يتم التعامل مع الملفات الموجودة في المحتوى المشترك لـ BeeWare Docs Tools على أنها محتوى "محلي". لذلك، ستستخدم إما اسم الملف فقط، كما في -8<- "docs-style-guide.md"، أو إذا كان المحتوى موجودًا في دليل فرعي، فستستخدم الدليل واسم الملف فقط، كما في -8<- "style/docs-style-guide.md".
  • إذا كنت تضمّن محتوى خارجيًا من ملف على GitHub عبر عنوان URL، فيجب عليك استخدام عنوان URL للمحتوى الخام، وإلا فسيتم عرض صفحة الويب بالكامل مضمنة في المكان الذي تضمّنه فيه.

استخدام الماكرو لإدراج محتوى من BeeWare Docs Tools المحتوى المشترك

يمكنك أيضًا تضمين محتوى من دليل المحتوى المشترك لأدوات BeeWare Docs باستخدام المكوّن الإضافي Macros MkDocs. هذه الطريقة ضرورية إذا كان المستند يحتوي على توجيهات Jinja التي يجب تنفيذها، ويجب استخدامها فقط في هذه الحالة. لن تعمل مع المحتوى الخارجي عبر عنوان URL. تعمل آلية استبدال المتغيرات Macros مع هذه الطريقة.

هناك خيارات لإدراج المحتوى باستخدام الماكرو:

  1. استخدم صيغة Jinja include إذا كنت تريد تضمين المستند دون إجراء أي تغييرات يدوية أخرى عليه.

  2. استخدم صيغة Jinja extends إذا كنت قد أدرجت صيغة Jinja block في المستند، والتي تسمح لك بتجاوز أو إضافة أقسام محددة.

pyspelling

نحن نستخدم مدقق الإملاء pyspelling. يتم تشغيله أثناء عمليات فحص الأخطاء البرمجية.

عندما يحدد pyspelling كلمة بها خطأ إملائي، في معظم الحالات، يجب تصحيحها في محتوى الوثائق.

في الحالات النادرة التي يتم فيها التعرف على كلمة صحيحة غير موجودة في قاموس pyspelling، لديك خياران:

  1. إذا كانت الكلمة من المحتمل أن يتم إعادة استخدامها عدة مرات، فيجب إضافة الكلمة إلى مستند spelling_wordlist في دليل docs، مرتبة حسب الترتيب الأبجدي.
  2. إذا كانت الكلمة غير مرجح أن تستخدم مرة أخرى، يمكنك وضعها بين علامتي <nospell> / </nospell>، وستتجاهلها pyspelling في السطر.