مشروع تجريبي مشارك في الأداء

تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات Google".

ملخّص المشروع

مؤسسة مفتوحة المصدر:

برنامج تجريبي مشارك للأداء

الكاتب الفني:

arzoo14

اسم المشروع:

تحويل محتوى مجالات مشروع الكتاب إلى تنسيق readthedocs وreStructuredText بالإضافة إلى هدف إضافي لتحسين المخططات البيانية

مدة المشروع:

المدة العادية (3 أشهر)

وصف المشروع

الخلاصة:

يلعب الموقع الإلكتروني للمنتدى دورًا أساسيًا في مؤسسة البرامج المفتوحة المصدر لأنّه ينشر فكرة العروض التي يوفّرها المنتدى، ومساهماته القيّمة، ومهاراته، ومستنداته، وأدلّته التعليمية، وما إلى ذلك. لذلك، سيهدف مشروعي إلى زيادة سهولة الاستخدام لجميع المساهمين في البرامج المفتوحة المصدر من خلال نقل محتوى مجالات مشاريع الكتب وتعديله، أي محتوى docbook ومستندات REST API ومحتوى pbench markdown إلى تنسيق reStructuredText حتى يمكن استضافته على الموقع الإلكتروني الحديث للمنتدى readthedocs.io. سيستفيد من هذا المشروع أيضًا المساهمون في المنتدى من خلال السماح لهم بتغيير هذا المحتوى وإضافته بسهولة أكبر. بالإضافة إلى ذلك، كهدف إضافي، سيتم تحسين المخططات البيانية في المستندات لمنحها مظهرًا أكثر احترافية.

الاقتراح:

1. نظرة عامة: تتوفّر مستندات "مساعِد الأداء" حاليًا بعدة تنسيقات مختلفة. وتشمل هذه الكتب حول PCP بتنسيق docbook وواجهة برمجة التطبيقات REST API بتنسيق صفحات man ومراجع pbench بتنسيق markdown. لذلك، لاحظت مجموعة المطوّرين الحاليين في المؤسسة أنّهم بحاجة إلى حلّ لا يتطلّب صيانة قدر الإمكان، ويسمح لمجتمع المطوّرين بالتركيز بالكامل على صيانة المحتوى بطريقة سهلة ومبسّطة. لذا، وفقًا للاحتياجات الحالية للمؤسسة، سأنفذ الأهداف التالية خلال موسم Google هذا من المستندات:

   1. تحويل محتوى docbook إلى تنسيق reStructuredText واستضافته على موقع readthedocs الإلكتروني
   2. تحويل مستندات واجهة برمجة التطبيقات REST API من صفحة man إلى تنسيق يناسب المطوّرين، أي تنسيق reStructuredText واستضافتها على موقع readthedocs الإلكتروني
   3. تحويل محتوى pbench MarkDown إلى تنسيق reStructuredText واستضافته على موقع readthedocs الإلكتروني
   4. وتشمل الأهداف الطموحة تحسين المخططات البيانية الواردة في المستندات.

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

سأساعد المؤسسة في التغلب على هذه القيود خلال هذه الفعالية من خلال تنسيق reStructuredText وRead the Docs (RTD) وSphinx.

تعمل خدمة Read the Docs (RTD) على تبسيط مستندات البرامج من خلال التشغيل الآلي لإنشاء مستنداتنا وتحديد إصداراتها واستضافتها نيابةً عنا. وهي منصة استضافة للمستندات التي يتم إنشاؤها باستخدام Sphinx. ويستفيد من إمكانات Sphinx ويضيف ميزات التحكّم في الإصدارات والبحث عن النص الكامل وغيرها من الميزات المفيدة. فهي تسحب التعليمات البرمجية وملفات المستندات من Git أو Mercurial أو Subversion، ثم تنشئ وثائقنا وتستضيفها. سنستخدم GitHub في مشروعنا لأنه النظام الأكثر استخدامًا للوصول إلى التعليمة البرمجية.

للبدء، سننشئ حسابًا على Read the Docs ونربط حساب GitHub. ثم سنختار مستودع جيت هب الذي نرغب في وضع وثائق له، وعندها يحدث السحر.

قراءة المستندات سوف: - استنساخ مستودعنا. - إنشاء نُسخ HTML وPDF وePub من مستنداتنا من الفرع الرئيسي - فهرسة مستنداتنا للسماح بالبحث عن النص الكامل - إنشاء عناصر الإصدار من كل علامة وفرع في مستودعنا، ما يتيح لنا استضافتها أيضًا اختياريًا - تفعيل رابط ويب في مستودعنا، وذلك لكي تتم إعادة إنشاء مستنداتنا عند دفع الرمز إلى أي فرع.

Sphinx هو أداة موثوقة لإنشاء المستندات تتضمّن العديد من الميزات الرائعة لكتابة المستندات الفنية، بما في ذلك: - إنشاء صفحات ويب وملفات PDF قابلة للطباعة ومستندات لأجهزة القراءة الإلكترونية (ePub) وغير ذلك، وكل ذلك من المصادر نفسها - يمكننا استخدام reStructuredText لكتابة المستندات. - نظام واسع النطاق للرجوع إلى الرموز البرمجية والمستندات - عيّنات من الرموز البرمجية التي تم تمييز بنيتها - منظومة متكاملة نشطة من الإضافات التابعة للطرف الأول والطرف الثالث

سأبدأ بتحويل كتابَي PCP المتوفّرين بتنسيق دفتر المستندات إلى التنسيق الأول، بعد تحويل وثائق واجهة برمجة تطبيقات REST من التنسيق الأول إلى التنسيق الأول، ثم تحويل محتوى Markdown إلى التنسيق الأول، وفي النهاية، استضافة كل هذه الكتب على موقع readthedocs. وتشمل الأهداف الطموحة تحسين المخططات البيانية في المستندات.

2.1. التحويل إلى تنسيق restructuredText: ستتمثّل الخطوة الأولى في تحويل محتوى الوثائق إلى تنسيق restructuredText. سيكون لكل فصل ملف rst منفصل يحتوي على محتوى ذلك الفصل فقط. على سبيل المثال، يتضمّن دليل مستخدم "مساعِد الأداء" ومشرفه ثمانية فصول. وهذا يعني أنّه سيكون هناك ثمانية ملفات rst مختلفة تتوافق مع هذه الفصول الثمانية. يكون اسم الملف الأول مماثلاً لاسم الفصل لتجنب أي لبس في المستقبل. ستتوفّر قائمة بالأشكال والجداول وقوائم الأمثلة في ثلاثة ملفات rst مختلفة. سيتم ربط المحتوى rst بالكامل برابط تشعبي بالطريقة نفسها التي يظهر بها حاليًا. سيتم استخدام الأسلوب نفسه لمستندات واجهة برمجة التطبيقات REST ومحتوى pbench. وسيتم الاهتمام بجميع العناصر الضرورية، مثل الخط الغامق والمائل والتسطير والنقاط النقطية والجداول وحجم الخط ونمط التعليمات البرمجية وحجم الصورة والمحاذاة، وما إلى ذلك أثناء تحويل المحتوى إلى التنسيق الأول.

2.2. دمج البداية مع Sphinx:

---

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

يستخدم ReadtheDocs Sphinx وreStructuredText (rst) كإعدادات تلقائية. بما أنّ Sphinx مثبَّت مسبقًا في نظامي، سأبدأ بإنشاء دليل داخل المشروع (يُسمى "مستندات Performance Co-Pilot") لتضمين المستندات: $ cd /path/to/project $ mkdir docs

بعد ذلك، يمكنك تشغيل sphinx-quickstart في هذا المسار: $ cd docs $ sphinx-quickstart

سترشدك هذه الخطوات السريعة إلى إنشاء الإعدادات اللازمة. في معظم الحالات، يمكننا قبول الإعدادات التلقائية فقط (ولكن يمكننا إجراء التغييرات الأساسية في ملف الإعدادات عند الحاجة). عند الانتهاء، سيكون لدينا index.rst وconf.py وبعض الملفات الأخرى. في الفهرس.rst، سأضيف جميع التفاصيل اللازمة حول "البرنامج التجريبي للأداء المشترك" وسأنشئ عناوين لكل من الكتب ووثائق واجهة برمجة تطبيقات REST وأدلّة الاستخدام التجريبي. عندما ينقر المستخدم فوق أي من العناوين، سيفتح جميع مواد الوثائق تحت هذا العنوان.

---

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

سيتم تضمين index.rst في index.html في دليل إخراج الوثائق (عادةً _build/html/index.html). بعد حصولنا على وثائق Sphinx في مستودع عام، يمكننا البدء باستخدام ميزة "قراءة المستندات" عن طريق استيراد مستنداتنا.

عندما نضيف أي ملف rst .في وثائقنا، ثم نقابل هذا الملف، سيتم إنشاء ثلاثة ملفات أخرى، واحد في مجلد doctrees بامتداد doctree .والثاني في مجلد Html بامتداد html.، والثالث في مجلد html/_sources بامتداد .rst.txt.

1. استضافة المستندات: تتطلّب استضافة المستندات على الإنترنت خطوتَين: 1. استيراد المستندات: كخطوة أولى، سأربط حساب Read The Docs بحساب GitHub وأستورِد مشروع المستندات لبناء الإصدار. 2. إنشاء الوثائق: في غضون ثوانٍ قليلة من اكتمال عملية الاستيراد، سيتم جلب الرمز تلقائيًا من مستودعنا العام، وسيتم إنشاء الوثائق.

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

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

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

---

ملاحظة: سيبدأ جميع الأعمال من المستوى الأساسي وسيتوفّر في مستودع منفصل باسم "مستندات الأداء المشترك في البرنامج التجريبي".

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

لتحقيق هذا الغرض، سأستخدم draw.io (أو أي أداة أخرى بموافقة المرشد).

كإثبات للفكر، قمت بتحسين أحد المخططات الموجودة في الوثائق بمساعدة برنامج draw.io. يمكنك العثور عليه هنا: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

إثبات المفهوم

لقد حوّلتُ جزءًا صغيرًا من كتاب PCP (بتنسيق docbook) إلى تنسيق rst واستضفّته على موقع readthedocs الإلكتروني. يمكنك العثور عليه هنا.

الموقع الإلكتروني: https://pcp-books.readthedocs.io/en/latest/ الرمز البرمجي: https://github.com/arzoo14/PCP_Books_Demo

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

الجدول الزمني والمواد المطلوب تسليمها

فترة التفاعل مع المنتدى [ 17 آب (أغسطس) - 13 أيلول (سبتمبر) 2020 ]

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

فترة تطوير المستندات [ من 14 أيلول (سبتمبر) إلى 30 تشرين الثاني (نوفمبر) 2020 ]

***من 14 أيلول (سبتمبر) 2020 إلى 20 أيلول (سبتمبر) 2020 [الأسبوع 1] تحويل محتوى docbook إلى تنسيق rst للأربعة فصول الأولى من كتاب "دليل المستخدمين والمشرفين"

***من 21 أيلول (سبتمبر) 2020 إلى 27 أيلول (سبتمبر) 2020 [الأسبوع 2] تحويل محتوى دفتر المستندات إلى التنسيق الأول للفصول الأربعة التالية من كتاب "دليل المستخدمين والمشرفين".

***من 28 أيلول (سبتمبر) 2020 إلى 4 تشرين الأول (أكتوبر) 2020 [الأسبوع 3] تحويل محتوى دفتر المستندات إلى التنسيق الأول لجميع الفصول الأربعة من كتاب "دليل المبرمج"

***من 5 تشرين الأول (أكتوبر) 2020 إلى 11 تشرين الأول (أكتوبر) 2020 [الأسبوع 4] - استضافة كلا كتابَي PCP على موقع readthedocs الإلكتروني - تحويل وثائق واجهة برمجة تطبيقات REST من الصفحة الرئيسية إلى التنسيق الأول. وسيتم تغطية الصفحة المقصودة الرئيسية خلال هذه الفترة. - التدوين (حول مشروع GSoD) للأسابيع الثلاثة الماضية والأسبوع الحالي

***من 12 تشرين الأول (أكتوبر) 2020 إلى 18 تشرين الأول (أكتوبر) 2020 [الأسبوع 5] تحويل فهرس السلسلة الزمنية القابلة للتوسيع إلى تنسيق rst يغطي فهرس السلاسل الزمنية القابل للتوسع ما يلي: GET /series/query ، GET /series/values ، GET /series/descs ، وGET /series/labels ، وGET /series/metrics ، وGET /series/sources ، وGET /series/instances ، وGET /series/loads

***من 19 تشرين الأول (أكتوبر) 2020 إلى 25 تشرين الأول (أكتوبر) 2020 [الأسبوع 6] تحويل فهرس خدمات مضيف PMAPI إلى تنسيق rst يشمل فهرس خدمات مضيف PMAPI ما يلي: GET ‎ /pmapi/context وGET ‎ /pmapi/metric وGET ‎ /pmapi/fetch وGET ‎ /pmapi/children GET ‎ /pmapi/indom وGET ‎ /pmapi/profile وGET ‎ /pmapi/store وGET ‎ /pmapi/derive GET ‎ /pmapi/metrics

***من 26 تشرين الأول (أكتوبر) 2020 إلى 1 تشرين الثاني (نوفمبر) 2020 [الأسبوع 7] - إذا تبقى أيّ شيء في الأسابيع الأخيرة، سيتمّ تناوله أولاً. - استضافة مستندات واجهة برمجة التطبيقات REST API على موقع readthedocs الإلكتروني - التدوين (حول مشروع GSoD) للأسبوعَين الماضيَين والأسبوع الحالي

***من 2 تشرين الثاني (نوفمبر) 2020 إلى 8 تشرين الثاني (نوفمبر) 2020 [الأسبوع 8] تحويل محتوى Markdown إلى تنسيق rst لأدلّة pbench

***من 9 تشرين الثاني (نوفمبر) 2020 إلى 15 تشرين الثاني (نوفمبر) 2020 [الأسبوع 9] - تم مواصلة تحويل محتوى Markdown إلى تنسيق rst لأدلّة pbench. - استضافة أدلة pbench على موقع readthedocs الإلكتروني - التدوين (حول مشروع GSoD) للأسبوع الماضي والأسبوع الحالي

***من 16 تشرين الثاني (نوفمبر) 2020 إلى 22 تشرين الثاني (نوفمبر) 2020 [الأسبوع 10] - تنفيذ وظيفة البحث في صفحة الفهرس للبحث عن أي محتوى من اسمه في المواقع الإلكترونية. - بدء أهداف التوسيع.

***من 23 تشرين الثاني (نوفمبر) 2020 إلى 30 تشرين الثاني (نوفمبر) 2020 [الأسبوع 11] - تحسين جميع المخططات البيانية الواردة في المستندات - التدوين النهائي (لمشروعي على GSoD) خلال الأسبوع الماضي والأسبوع الحالي. - التحقق مما إذا كانت قاعدة التعليمات البرمجية متوافقة مع معايير التعليمات البرمجية أم لا. وإذا لم يكن الأمر كذلك، يجب تغييرها إلى المعايير.

فترة الانتهاء من المشروع [ 30 تشرين الثاني (نوفمبر) - 5 كانون الأول (ديسمبر) 2020 ]

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