19. ملحق: المساهمة في هذا الدليل

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

19.1. تنزيل الموارد

مصدر هذا المستند متاح على GitHub. راجع GitHub.com للاطلاع على تعليمات استخدام نظام التحكم في الإصدارات git.

19.2. تنسيق الدليل

كُتب هذا الدليل باستخدام Sphinx، وهو مولّد مستندات مكتوب بلغة Python يستخدم لغة الترميز reStructuredText. تتوفر تعليمات استخدام هذه الأدوات على مواقعها الخاصة.

19.3. إضافة وحدة

لإضافة وحدة جديدة:

  1. أنشئ أولًا مجلدًا جديدًا (مباشرةً تحت المستوى الأعلى للمجلد qgis-training-manual) يحمل اسم الوحدة الجديدة.

  2. داخل هذا المجلد الجديد، أنشئ ملفًا باسم index.rst. اترك هذا الملف فارغًا في الوقت الحالي.

  3. افتح الملف index.rst الموجود في المجلد الأعلى. أسطره الأولى هي:

    .. toctree::
   :maxdepth: 2

   foreword/index
   introduction/index

ستلاحظ أن هذه قائمة بأسماء المجلدات، يلي كلًّا منها الاسم index. يوجّه هذا ملف الفهرس الأعلى إلى ملفات الفهرس في كل مجلد. ويحدد الترتيب الذي تُدرج به ترتيبها في المستند.

  1. أضف اسم وحدتك الجديدة (أي الاسم الذي أعطيته للمجلد الجديد)، متبوعًا بـ /index، إلى هذه القائمة في الموضع الذي تريد أن تظهر فيه وحدتك.

  2. تذكّر أن تحافظ على ترتيب منطقي للوحدات، بحيث تبني الوحدات اللاحقة على المعرفة المقدَّمة في الوحدات السابقة.

  3. افتح ملف الفهرس الخاص بوحدتك الجديدة (module_name/index.rst).

  4. في أعلى الصفحة، أنشئ عنوان الوحدة:

    1. اكتب سطرًا أول من النجوم (*).

    2. أتبِعه بسطر يحتوي على عبارة الترميز Module:، متبوعة باسم وحدتك.

    3. اختم ذلك بسطر آخر يحتوي على العدد نفسه من النجوم.

    ملاحظة

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

  5. اترك سطرًا فارغًا أسفل ذلك.

  6. اكتب فقرة قصيرة تشرح الغرض من الوحدة ومحتواها.

  7. اترك سطرًا فارغًا، ثم أضف النص التالي:

    .. toctree::
   :maxdepth: 2

   lesson1
   lesson2

    ... حيث lesson1 و lesson2 وغيرها هي أسماء الدروس التي تخطط لها.

سيبدو ملف الفهرس على مستوى الوحدة كما يلي:

*******************************************************************************
Module: Module Name
*******************************************************************************

Short paragraph describing the module.

.. toctree::
   :maxdepth: 2

   lesson1
   lesson2

19.4. إضافة درس

لإضافة درس إلى وحدة جديدة أو موجودة:

  1. افتح مجلد الوحدة.

  2. افتح الملف index.rst (الذي أُنشئ أعلاه في حالة الوحدات الجديدة).

  3. تأكد من أن اسم الدرس المخطط له مدرج تحت التوجيه toctree، كما هو موضح أعلاه.

  4. أنشئ ملفًا جديدًا داخل مجلد الوحدة.

  5. سمِّ هذا الملف بالاسم نفسه تمامًا الذي وضعته في ملف index.rst الخاص بالوحدة، وأضف إليه الامتداد .rst.

ملاحظة

لأغراض التحرير، يعمل ملف .rst تمامًا مثل ملف نصي عادي (.txt).

  1. لبدء كتابة الدرس، اكتب عبارة الترميز Lesson، متبوعة باسم الدرس.

  2. في السطر التالي، اكتب سطرًا من علامات المساواة (=)، لا يكون أقصر من عنوان الدرس.

  3. اترك سطرًا فارغًا بعد ذلك.

  4. اكتب وصفًا قصيرًا للغرض المقصود من الدرس.

  5. ضمِّن مقدمة عامة عن الموضوع. راجع الدروس الموجودة في هذا الدليل للاطلاع على أمثلة.

  6. أسفل ذلك، ابدأ فقرة جديدة تبدأ بهذه العبارة:

    **The goal for this lesson:**

  7. اشرح باختصار النتيجة المرجوة من إكمال هذا الدرس.

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

سيُقسَّم كل درس إلى عدة أقسام، سنتناولها فيما يلي.

19.5. إضافة قسم

هناك نوعان من الأقسام: "تابع معنا" و"جرّب بنفسك".

  • قسم "تابع معنا" هو مجموعة مفصلة من التوجيهات تهدف إلى تعليم القارئ كيفية استخدام جانب معين من QGIS. ويتم ذلك عادةً بتقديم توجيهات نقرة بنقرة بأكبر قدر ممكن من الوضوح، تتخللها لقطات شاشة.

  • يقدم قسم "جرّب بنفسك" للقارئ مهمة قصيرة ليجربها بنفسه. ويرتبط عادةً بمدخل في مربع الإجابة أسفله، يُظهر أو يشرح كيفية إنجاز المهمة، ويعرض النتيجة المتوقعة إن أمكن.

لكل قسم مستوى صعوبة. يُشار إلى القسم السهل بـ ★☆☆، والمتوسط بـ ★★☆، والمتقدم بـ ★★★.

19.5.1. إضافة قسم "تابع معنا"

  1. لبدء هذا القسم، اكتب عبارة الترميز الخاصة بمستوى الصعوبة المقصود (كما هو موضح أعلاه).

  2. اترك مسافة ثم اكتب Follow Along:.

  3. اترك مسافة أخرى واكتب اسم القسم (استخدم حرفًا كبيرًا في البداية فقط، بالإضافة إلى الأحرف الكبيرة لأسماء العلم).

  4. في السطر التالي، اكتب سطرًا من علامات الطرح/الشرطات (-)، لا يكون أقصر من عنوان القسم.

  5. اكتب مقدمة قصيرة للقسم تشرح الغرض منه. ثم قدّم تعليمات مفصلة (نقرة بنقرة) للإجراء المراد شرحه.

  6. في كل قسم، ضمِّن روابط داخلية وروابط خارجية ولقطات شاشة حسب الحاجة.

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

19.5.2. إضافة قسم "جرّب بنفسك"

  1. لبدء هذا القسم، اكتب عبارة الترميز الخاصة بمستوى الصعوبة المقصود (كما هو موضح أعلاه).

  2. اترك مسافة ثم اكتب Try Yourself:.

  3. في السطر التالي، اكتب سطرًا من علامات الطرح/الشرطات (-)، لا يكون أقصر من عنوان القسم.

  4. اشرح التمرين الذي تريد من القارئ إكماله. وارجع إلى الأقسام أو الدروس أو الوحدات السابقة عند الضرورة.

  5. ضمِّن لقطات شاشة لتوضيح المتطلبات إذا لم يكن الوصف النصي البسيط واضحًا.

في معظم الحالات، ستحتاج إلى تقديم إجابة توضح كيفية إنجاز المهمة المعطاة في هذا القسم. وللقيام بذلك، ستحتاج إلى إنشاء كتلة إجابة أسفل التعليمات وملئها.

  1. أولًا، أنشئ عنصر الواجهة المخصص القابل للطي الذي يحتوي على الإجابة:

    .. admonition:: Answer
   :class: dropdown

  2. مع الحفاظ على إزاحة بالنسبة إلى الكتلة أعلاه، اكتب التعليمات الخاصة بكيفية إنجاز المهمة، مستخدمًا الروابط والصور عند الحاجة.

19.6. إضافة خلاصة

لإنهاء درس:

  1. اكتب العبارة In Conclusion، متبوعة بسطر جديد من علامات الطرح/الشرطات (-).

  2. اكتب خلاصة للدرس توضح المفاهيم التي غطاها الدرس.

19.7. إضافة قسم للقراءات الإضافية

هذا القسم اختياري.

  • اكتب العبارة Further Reading، متبوعة بسطر جديد من علامات الطرح/الشرطات (-).

  • ضمِّن روابط إلى مواقع ويب خارجية مناسبة.

19.8. إضافة قسم "ما التالي"

  1. اكتب العبارة What's Next?، متبوعة بسطر جديد من علامات الطرح/الشرطات (-).

  2. اشرح كيف هيّأ هذا الدرسُ الطلابَ للدرس أو الوحدة التالية.

  3. تذكّر تعديل قسم "ما التالي" في الدرس السابق عند الضرورة، بحيث يشير إلى درسك الجديد. سيكون ذلك ضروريًا إذا أدرجت درسًا جديدًا بين دروس موجودة، أو بعد درس موجود.

19.9. استخدام الترميز

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

19.9.1. المفاهيم الجديدة

إذا كنت تشرح مفهومًا جديدًا، فستحتاج إلى كتابة اسم المفهوم الجديد بخط مائل عبر إحاطته بنجمتين مفردتين (*).

This sample text shows how to introduce a *new concept*.

19.9.2. التأكيد

  • للتأكيد على مصطلح مهم ليس مفهومًا جديدًا، اكتب المصطلح بخط عريض عبر إحاطته بنجمتين مزدوجتين (**).

  • استخدم ذلك باعتدال! فإذا أفرطت في استخدامه، فقد يبدو للقارئ أنك تصرخ أو تتعالى عليه.

This sample text shows how to use **emphasis** in a sentence. Include the
punctuation mark if it is followed by a **comma,** or at the **end of the
sentence.**

19.9.3. مرئية

  • عند إضافة صورة، احفظها في مجلد img بجوار ملف الدرس.

  • ضمِّنها في المستند على هذا النحو:

    .. figure:: img/image_file.extension
   :align: center

  • تذكّر أن تترك سطرًا فارغًا أعلى ترميز الصورة وأسفله.

19.9.6. استخدام النص أحادي المسافة

  • عندما تكتب نصًا يحتاج المستخدم إلى إدخاله، أو اسم مسار، أو اسم عنصر في قاعدة بيانات مثل اسم جدول أو عمود، فيجب عليك كتابته بـ monospaced text. على سبيل المثال:

    Enter the following path in the text box: ``path/to/file``.

19.9.7. تسمية عناصر الواجهة الرسومية

  • إذا كنت تشير إلى عنصر في الواجهة الرسومية، مثل زر، فيجب عليك كتابة اسمه بتنسيق the GUI label format. على سبيل المثال:

    To access this tool, click on the :guilabel:`Tool Name` button.

  • ينطبق هذا أيضًا إذا كنت تذكر اسم أداة دون أن تطلب من المستخدم النقر على زر.

19.9.9. إضافة الملاحظات

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

    [Normal paragraph.]

.. note:: Note text.
  New line within note.

  New paragraph within note.

[Unindented text resumes normal paragraph.]

19.9.10. إضافة ملاحظة رعاية/تأليف

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

إذا تطوعت لكتابة وحدة أو درس أو قسم بصفتك الشخصية، وليس نيابةً عن جهة راعية، فيمكنك تضمين ملاحظة تأليف أسفل عنوان الوحدة أو الدرس أو القسم الذي ألّفته. ويجب أن تكون بالصيغة This [module/lesson/section] contributed by [author name]. لا تُضف نصًا آخر أو بيانات اتصال أو ما شابه. فمثل هذه التفاصيل تُضاف في قسم "المساهمون" في التمهيد، مع اسم الجزء (أو الأجزاء) الذي أضفته. وإذا اقتصرت مساهمتك على التحسينات و/أو التصحيحات و/أو الإضافات، فأدرج اسمك بصفتك محررًا.

19.10. شكرًا لك!

شكرًا لمساهمتك في هذا المشروع! فبذلك تجعل QGIS أكثر سهولة في متناول المستخدمين وتضيف قيمة إلى مشروع QGIS ككل.