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

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

ملخص المشروع

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

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

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

برونوبيلتران

اسم المشروع:

تحسين قابلية اكتشاف الميزات من خلال توحيد عملية التوثيق للأنواع "الضمنية"

مدة المشروع:

الجري الطويل (5 أشهر)

وصف المشروع

الحافز

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

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

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

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

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

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

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

لاستخدام مثال linestyle مجددًا، ما نريده في مستندات LineCollection هو فقط:

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

الطريقة التي قد يبدو بها ذلك في مستندات 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 ليشير إلى مجموعة واحدة موثوقة وكاملة من المستندات حول كيفية تعامل مكتبة مات بلوت ليب مع الأنماط الخطية.

المزايا

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

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

تفوق المستندات الحالية لهذا النهج ما يلي:

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

التنفيذ

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

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

في حين أن التنسيق الدقيق للوثائق المقترحة هنا يخضع للتغيير مع تطور هذا المشروع، فقد عملتُ مع فريق Matplotlib الأساسي خلال "مكالمات المطورين" الأسبوعية للتوصل إلى إجماع على أن الاستراتيجية المقترحة هنا هي النهج الأكثر فائدة وفائدة وقابلية من الناحية الفنية لبدء توثيق هذه "الأنواع الضمنية" (تتوفر ملاحظات على هذه الطلبات) سأستخدم البنية الأساسية الحالية لـ "البرامج التعليمية" للمراحل الأولية من إنشاء المستندات المركزية لكل نوع ضمني، ما يتيح لي الرجوع إلى هذه الصفحات بسهولة على النحو التالي، بدون الحاجة إلى إنشاء أي فئات عامة جديدة (باستخدام مستندات 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 الحسنة النية، على سبيل المثال، على النحو الذي اقترحته في اقتراح تحسين مكتبة مات بلوت ليب 30.

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

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

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