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

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

ملخص المشروع

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

برنامج تجريبي مساعد الأداء

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

arzoo14

اسم المشروع:

يمكنك تحويل محتوى مناطق مشاريع الكتب إلى readthedocs وتنسيق reهيكلةText مع الهدف الموسّع لتحسين الرسومات البيانية.

مدة المشروع:

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

وصف المشروع

ملخص:

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

الاقتراح:

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

   1. تحويل محتوى دفتر المستندات إلى تنسيق reOrganizationText واستضافتها على موقع readthedocs
   2. تحويل وثائق واجهة برمجة التطبيقات REST من تنسيق صفحة manpage إلى تنسيق مناسب للمطوّرين، أي تنسيق reOrganizationText واستضافتها على موقع readthedocs
   3. تحويل محتوى pbench MarkDown إلى تنسيق re إدخالText واستضافتها على موقع readthedocs
   4. ستكون أهداف التوسيع هي تحسين المخططات الموجودة في الوثائق.

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

سأسمح للمؤسسة بتخطي هذه القيود خلال GSoD هذا بمساعدة تنسيق reOrganizationText وقراءة المستندات (RTD) وSphinx.

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

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

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

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

سأبدأ بتحويل كتابَي PCP المتوفّرَين بتنسيق docbook إلى التنسيق الأول، وذلك بعد تحويل وثائق واجهة برمجة تطبيقات REST من تنسيق صفحة man إلى تنسيق rst، ثم تحويل محتوى pbench markdown إلى التنسيق الأول، وأخيرًا استضافة كل هذه التنسيقات على موقع readthedocs الإلكتروني. ستكون أهداف التوسيع هي تحسين الرسوم البيانية في الوثائق.

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

2.2. دمج rst مع Sphinx:

---

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

يستخدم Readtheالمستندات Sphinx وreOrganizationText (rst) كإعدادات افتراضية. نظرًا لتثبيت Sphinx مسبقًا في نظامي، سأبدأ بإنشاء دليل داخل المشروع (يحمل اسم الوثائق التجريبية المشتركة للأداء) للاحتفاظ بالمستندات: $ cd /path/to/project $ مستندات mkdir

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

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

---

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

سيتم تضمين 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 (تنسيق دفتر المستندات) إلى التنسيق الأول واستضافته على موقع 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] تحويل محتوى دفتر المستندات إلى التنسيق الأول للفصول الأربعة الأولى من كتاب "دليل المستخدمين والمشرفين".

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

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

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

***من 12 تشرين الأول (أكتوبر) 2020 إلى 18 تشرين الأول (أكتوبر) 2020 [الأسبوع 5] تحويل فهرس السلسلة الزمنية القابلة للتوسع إلى التنسيق الأول. يشمل فهرس Scalable Time Series ما يلي: 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 إلى التنسيق الأول. يشمل فهرس الخدمات المضيفة من 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/derive

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

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

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

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

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

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

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