مشروع مكتبة مات بلوت ليب

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

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

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

مكتبة مات بلوت ليب

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

brunobeltran

اسم المشروع:

تحسين إمكانية العثور على الميزات من خلال توحيد مستندات الأنواع "الضمنية"

مدة المشروع:

الحمل لمدة طويلة (5 أشهر)

وصف المشروع

الحافز

في السابق، كانت واجهة برمجة التطبيقات في matplotlib تعتمد بشكل كبير على استخدام السلسلة بصفتها فهرسًا ""للأنواع الضمنية"". بالإضافة إلى محاكاة واجهة برمجة التطبيقات في matlab، تسمح سلاسل المَعلمات هذه للمستخدم بتمرير قيم غنية من الناحية الدلالية كوسيطات لدوالّ matplotlib بدون الحاجة إلى استيراد قيمة enum فعلية أو إضافة بادئة بشكل مفصّل لمجرد تمرير خيارات الرسم الأساسية (أي أنّ plt.plot(x, y, linestyle='solid') هو أسهل في الكتابة وأقل تكرارًا من plt.plot(x, y, linestyle=mpl.LineStyle.solid)).

وتطوّرت منذ ذلك الحين العديد من هذه الأنواع الضمنية التي تستخدم السلسلة بصفتها فهرسًا لتضمين ميزات أكثر تعقيدًا. على سبيل المثال، يمكن أن يكون linestyle الآن سلسلة أو ثنائية من التسلسلات، ويمكن أن يكون MarkerStyle الآن سلسلة أو matplotlib.path.Path. على الرغم من أنّ هذا ينطبق على العديد من الأنواع الضمنية، فإنّ MarkerStyle هو النوع الوحيد (حسب علمي) الذي تمت ترقيته إلى فئة Python مناسبة.

وبما أنّ هذه الأنواع الضمنية ليست فئات بحد ذاتها، كان على Matplotlib في السابق طرح حلولها الخاصة لتجميع المستندات والتحقق من هذه الأنواع الضمنية (مثل docstring.interpd.update docstring أنماط الاستبدال وcbook._check_in_list أنماط المدقّق، على التوالي) بدلاً من استخدام أدوات السلسلة المتسلسلة العادية التي تقدّمها فئات Python (مثل docstrings وأنماط validate-at-__init__، على التوالي).

على الرغم من أنّ هذه الحلول فعّالة بالنسبة إلينا، إلا أنّ عدم توفّر موقع صريح لتوثيق كل نوع ضمني يعني أنّه غالبًا ما يكون من الصعب العثور على المستندات، ويتم تكرار الجداول الكبيرة للقيم المسموح بها في المستندات، وغالبًا ما لا تتضمّن المستندات بيانًا صريحًا عن نطاق نوع ضمني. خذ مستندات plt.plot، على سبيل المثال: في ""الملاحظات""، يشير وصف أسلوب تنسيق سلسلة التنسيق المشابه لـ matlab إلى خيارات linestyle وcolor وmarkers. هناك طرق متعدّدة لإرسال هذه القيم الثلاث أكثر من تلك المُشار إليها، ولكن بالنسبة إلى العديد من المستخدِمين، هذا هو المصدر الوحيد لفهم القيم التي يمكن استخدامها في هذه الخيارات إلى أن يعثروا على أحد الأدلة التعليمية ذات الصلة. تم تضمين جدول سمات Line2D في محاولة لإظهار خيارات التحكّم في المخطط للقارئ. ومع ذلك، على الرغم من أنّ إدخال linestyle يؤدي بشكل جيد إلى الربط بصفحة Line2D.set_linestyle (تتطلب نقرتين ) التي يتم فيها وصف الإدخالات المحتملة، لا يؤدي إدخالا color وmarkers إلى ذلك. يرتبط color ببساطة بـ Line2D.set_color، وهذا لا يوفر أي فكرة عن أنواع الإدخالات المسموح بها حتى.

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

الهدف النهائي

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

لاستخدام مثال linestyle مرة أخرى، ما نريد تضمينه في مستندات LineCollection هو:

1. رابط يؤدي إلى المستندات الكاملة للعناصر المسموح بها (مجموعة من العناصر المتوفّرة في Line2D.set_linestyle ومستند تعليمات أسلوب الخط)
2. وصف بكلمات بسيطة لما تهدف إليه المَعلمة بالنسبة إلى مستخدمي matplotlib المتقدّمين، يكون هذا واضحًا من اسم المَعلمة، ولكن قد لا يكون الأمر كذلك بالنسبة إلى المستخدمين الجدد.

ستظهر هذه الطريقة في مستندات LineCollection الفعلية على النحو التالي: python """""" linestyles: `LineStyle` or list thereof, default: :rc:`lines.linestyle` ('-') A description of whether the stroke used to draw each line in the collection is dashed, dotted or solid, or some combination thereof. """""" حيث سيحلّ Sphinx مرجع نوع LineStyle للإشارة إلى مجموعة واحدة موثوقة وكاملة من المستندات حول كيفية تعامل Matplotlib مع أنماط الخطوط.

المزايا

تشمل بعض الميزات الفعّالة لهذا النهج ما يلي:

1. توضيح القيمة الكاملة لما تستطيع كل دالة إظهاره في النص العادي (بدون الحاجة إلى أي نقرات)
2. جعل الخيار التلقائي مرئيًا (بدون أي نقرات) غالبًا ما يكون ظهور الخيار التلقائي كافيًا لتذكير المستخدمين المتكررين باختيارهم السابق.
3. قدِّم وصفًا كاملاً للخيارَين "الأكثر شيوعًا" و"الأكثر سهولة" ل參مَرة متوفّرة بسهولة عند التصفّح (بنقرة واحدة).
4. يمكنك بسهولة الاطّلاع على ميزات وأساليب إدخال أكثر فعالية من خلال التمرير للأسفل (بنقرة واحدة فقط).
5. تقديم استراتيجية مركزية لربط مستندات ""واجهة برمجة التطبيقات"" ذات المستوى الأعلى بـ ""الأدلة الإرشادية"" ذات الصلة
6. تجنَّب تضخّم مستندات واجهة برمجة التطبيقات، حيث يؤدي فحص الخيارات العديدة الممكنة لكل مَعلمة إلى جعل مستندات وصف الدوال الفردية غير قابلة للاستخدام.

تتمثل المزايا الأخرى لهذا الأسلوب مقارنةً بالمستندات الحالية في ما يلي:

1. من غير المرجّح أن تصبح المستندات قديمة، وذلك بسبب تركيزها.
2. توحيد العديد من ""المعايير الضمنية"" في matplotlib (مثل الفرق بين ""bounds"" و""extents"") التي يجب حاليًا تعلمها من خلال قراءة الرمز البرمجي
3. ستسلط هذه العملية الضوء على المشكلات المتعلقة بتناسق واجهة برمجة التطبيقات بطريقة يمكن تتبعها بسهولة أكبر عبر أداة تتبع مشكلات GitHub، مما يساعد في عملية تحسين واجهة برمجة التطبيقات.
4. أوقات إنشاء المستندات أسرع بسبب الانخفاض الكبير في حجم النص الذي يحتاج إلى تحليل.

التنفيذ

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

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

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

""""""
linestyles: LineStyle or list thereof, default: :rc:`lines.linestyle` ('-')
    A description of whether the stroke used to draw each line in the collection
    is dashed, dotted or solid, or some combination thereof. For a full
    description of possible LineStyle's, see :doc:`tutorials/types/linestyle`.
""""""

من الآن فصاعدًا، يمكننا بسهولة تغيير طريقة كتابة هذه المراجع بمجرد موافقة فريق المطوّرين الأساسي على أفضل استراتيجية طويلة الأمد لدمج مستندات "الأنواع" الجديدة في فئات Python الحسنة، على سبيل المثال، كما اقترحتُ في اقتراح تحسين Matplotlib 30.

أخيرًا، في ما يلي القائمة الأولية للأنواع الضمنية التي نقترح توثيقها خلال موسم "مستندات Google" هذا:

1. capstyle
2. joinstyle
3. bounds
4. extents
5. linestyle
6. ‫colors/lists of colors
7. colornorm/colormap
8. tick formatters

يمكن العثور على نسخة صالحة من هذا المستند في الدورة التدريبية.