Matplotlib प्रोजेक्ट

इस पेज पर Google Docs के सीज़न के लिए स्वीकार किए गए एक तकनीकी लेखन प्रोजेक्ट की जानकारी है.

प्रोजेक्ट की खास जानकारी

ओपन सोर्स संगठन:

मैटप्लोटलिब

तकनीकी लेखक:

ब्रूनोबेलट्रान

प्रोजेक्ट का नाम:

“इंप्लिसिट” टाइप के दस्तावेज़ों के लिए स्टैंडर्ड तय करके, सुविधाओं को आसानी से खोजने लायक बनाना

प्रोजेक्ट की अवधि:

लंबे समय तक दौड़ना (पांच महीने)

प्रोजेक्ट का विवरण

वजह

पहले से ही, matplotlib का एपीआई बहुत स्ट्रिंग-as-enum "" प्रक्रिया के टाइप"" पर काफ़ी निर्भर रहा है. matlab के एपीआई की तरह दिखने वाले पैरामीटर के अलावा, ये पैरामीटर-स्ट्रिंग उपयोगकर्ता को matplotlib फ़ंक्शन के लिए तर्क के रूप में सिमेंटिक तौर पर बेहतर वैल्यू पास करने की अनुमति देती हैं. इसके लिए, बेसिक प्लॉट विकल्प को पास करने के लिए, साफ़ तौर पर एनम वैल्यू को साफ़ तौर पर इंपोर्ट या शुरू करने की ज़रूरत नहीं होती (यानी plt.plot(x, y, linestyle='solid') टाइप करना आसान है और plt.plot(x, y, linestyle=mpl.LineStyle.solid) जैसी चीज़ों की तुलना में कम बेकार है).

तब से इनमें से कई स्ट्रिंग-ए-एनम इंप्लिसिट टाइप में और भी बेहतर सुविधाएं जोड़ी गई हैं. उदाहरण के लिए, linestyle अब या तो स्ट्रिंग या दो क्रमों का टुकड़ा हो सकता है और मार्कर स्टाइल अब स्ट्रिंग या matplotlib.path.Path हो सकता है. हालांकि, यह कई तरह के इंप्लिसिट टाइप के लिए सही है, लेकिन \rStyle सिर्फ़ एक ऐसी (मेरी जानकारी के हिसाब से) है जिसमें सही Python क्लास में अपग्रेड किए जाने की स्थिति है.

ये इंप्लिसिट टाइप अपने-आप क्लास नहीं हैं, इसलिए Python क्लास से मिले स्टैंडर्ड टूलचेन (जैसे, docstrings__init__ और अलग-अलग) का इस्तेमाल करने के बजाय, Matplotlib को पहले से ही दस्तावेज़ों को एक ही जगह पर लाने और इन इंप्लिसिट टाइप (जैसे कि docstring.interpd.update डॉकस्ट्रिंग प्रक्षेप पैटर्न और cbook._check_in_list पुष्टि करने वाले पैटर्न) के लिए खुद के समाधान लाने पड़ते थे.

हालांकि, इन समाधानों ने हमारे लिए अच्छी परफ़ॉर्मेंस दी है, लेकिन हर इंप्लिसिट टाइप को दर्ज करने के लिए, जगह की सटीक जानकारी न होने का मतलब है कि दस्तावेज़ ढूंढना अक्सर मुश्किल होता है. साथ ही, अनुमति वाली वैल्यू की बड़ी टेबल को पूरे दस्तावेज़ में दोहराया जाता है. साथ ही, अक्सर किसी इंप्लिसिट टाइप के स्कोप की साफ़ तौर पर जानकारी, दस्तावेज़ों में मौजूद नहीं होती. उदाहरण के लिए, plt.plot दस्तावेज़ों का इस्तेमाल करें: ""Notes"" में matlab जैसे फ़ॉर्मैट-स्ट्रिंग शैली के तरीके की जानकारी में linestyle, color, और markers विकल्पों का ज़िक्र किया गया है. बताए गए तरीकों के अलावा, इन तीन वैल्यू को पास करने के और भी तरीके हैं. हालांकि, कई उपयोगकर्ताओं के लिए, यह समझने का इकलौता ऐसा सोर्स होता है कि उन विकल्पों के लिए क्या-क्या वैल्यू मिल सकती हैं. ऐसा तब तक होता है, जब तक कि वे काम के ट्यूटोरियल वाले किसी ट्यूटोरियल से न चूक जाएं. Line2D एट्रिब्यूट की एक टेबल के ज़रिए लोगों को यह दिखाया जाता है कि प्लॉट को कंट्रोल करने के लिए, उनके पास कौनसे विकल्प हैं. हालांकि, जहां संभव इनपुट बताए गए हैं वहां linestyle एंट्री, Line2D.set_linestyle (दो क्लिक ज़रूरी) से लिंक करने का अच्छा काम करती है, लेकिन color और markers एंट्री को लिंक नहीं किया जा सकता. color सिर्फ़ Line2D.set_color से लिंक करता है, जिससे यह पता नहीं चलता कि किस तरह के इनपुट दिए जा सकते हैं.

यह तर्क दिया जा सकता है कि इस तरह की चीज़ों को समस्या पैदा करने वाली अलग-अलग डॉकस्ट्रिंग को ठीक करके ठीक किया जा सकता है, लेकिन यह अच्छी बात है कि यह समस्या इससे कहीं ज़्यादा व्यवस्थित है. दस्तावेज़ ढूंढने के लिए कोई सेंट्रलाइज़्ड स्पेस न होने पर, इस तरह के दस्तावेज़ों की ज़्यादा से ज़्यादा कॉपी हमें मिलेंगी. हर जगह इस तरह के इंप्लिसिट दस्तावेज़ इस्तेमाल किए जाते हैं. इससे शुरुआत करने वाले उपयोगकर्ताओं के लिए अपनी ज़रूरत का पैरामीटर ढूंढना और भी मुश्किल हो जाता है. हालांकि, मौजूदा सिस्टम, जो उपयोगकर्ताओं को हमारे पूरे दस्तावेज़ में विकी-डाइविंग स्टाइल ट्रैवर्सल के ज़रिए, हर इंप्लिसिट टाइप के अपने मानसिक मॉडल को धीरे-धीरे इकट्ठा करने के लिए मजबूर करता है, या 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. """""" जहां LineStyle टाइप के रेफ़रंस का समाधान निकालना

फ़ायदे

इस तरीके की कुछ दमदार सुविधाओं में ये शामिल हैं:

1. इस बात की पूरी जानकारी देना कि हर फ़ंक्शन को सादे टेक्स्ट में कितनी आसानी से समझा जा सकता है (इसमें शून्य क्लिक होना ज़रूरी है).
2. डिफ़ॉल्ट विकल्प को दिखने लायक बनाना (शून्य क्लिक के साथ). डिफ़ॉल्ट विकल्प देखना अक्सर वापस लौटने वाले उपयोगकर्ताओं की मेमोरी को ट्रैक करने के लिए काफ़ी होता है.
3. ब्राउज़ करते समय आसानी से उपलब्ध पैरामीटर के लिए (एक क्लिक में) ""सबसे सामान्य"" और ""सबसे आसान"" विकल्पों की पूरी जानकारी दें.
4. ज़्यादा बेहतर सुविधाओं और इनपुट के तरीकों को खोजने की प्रोसेस को, ज़्यादा बेहतर विकल्प देखने के लिए ""नीचे स्क्रोल करें"" जितना आसान बनाएं. ऐसा सिर्फ़ एक क्लिक से किया जा सकता है.
5. टॉप लेवल ""एपीआई"" दस्तावेज़ों को काम के ""ट्यूटोरियल"" से लिंक करने के लिए, एक ही जगह पर लाइसेंस रणनीति दें.
6. एपीआई-डॉक-एक्सप्लोज़न से बचें, क्योंकि हर पैरामीटर के कई संभावित विकल्पों को स्कैन करने से, अलग-अलग डॉकस्ट्रिंग को काम करना मुश्किल हो जाता है.

मौजूदा दस्तावेज़ों की तुलना में, इस तरीके के अन्य फ़ायदे हैं:

1. दस्तावेज़ों को एक ही जगह से इकट्ठा करने की वजह से, दस्तावेज़ के पुराने होने की संभावना कम होती है.
2. मैटप्लोटलिब के कई ""इंप्लिसिट स्टैंडर्ड"" (जैसे कि ""सीमाएं"" बनाम ""एक्सटेंट"") में से कई को कैननिकल बनाना जिन्हें फ़िलहाल कोड को पढ़कर सीखा जाना ज़रूरी है.
3. यह प्रोसेस, एपीआई के एक जैसे वर्शन से जुड़ी समस्याओं को कुछ इस तरह हाइलाइट करेगी कि GitHub से जुड़ी समस्याओं को ट्रैक करने वाले टूल की मदद से, उसे आसानी से ट्रैक किया जा सके. इससे एपीआई को बेहतर बनाने में मदद मिलेगी.
4. पार्स करने के लिए ज़रूरी टेक्स्ट की मात्रा में काफ़ी कमी आने की वजह से, दस्तावेज़ तेज़ी से बनता है.

लागू करने का तरीका

ऊपर बताए गए सुधारों को बेहतर बनाने के लिए दो बड़े तरीकों की ज़रूरत होगी. इसके लिए, एक समर्पित तकनीकी लेखक अमूल्य होगा. पहला तरीका है, हर इंप्लिसिट टाइप के हिसाब से एक ""ट्यूटोरियल"" पेज बनाना. इसके लिए मुख्य डेवलपर टीम के साथ काम करने की ज़रूरत होगी, ताकि उन इंप्लिसिट टाइप की एक सटीक सूची की पहचान की जा सके जिनके दस्तावेज़ उपयोगकर्ताओं के लिए काम के होंगे. आम तौर पर, क्योंकि उनमें हमारी लाइब्रेरी की ऐसी असरदार छिपी सुविधाएं होती हैं जिनका दस्तावेज़, फ़िलहाल सिर्फ़ मुश्किल से भरे ट्यूटोरियल में मौजूद होता है. हर इंप्लिसिट टाइप के लिए, अलग-अलग तरह के काम के ट्यूटोरियल, एपीआई दस्तावेज़, और उदाहरण पेजों को दस्तावेज़ के एक ही आधिकारिक सोर्स में सिंथेसाइज़ किया जाएगा जिसे उस खास टाइप से जुड़े किसी भी दस्तावेज़ से लिंक किया जा सकता है.

दिए गए किसी इंप्लिसिट टाइप के लिए एक ही जगह पर उपलब्ध दस्तावेज़ के पूरा हो जाने के बाद, दूसरा अहम काम शुरू होता है: मौजूदा एपीआई दस्तावेज़ों को नए दस्तावेज़ों के लिंक से बदलना. इससे, इस नए दस्तावेज़ को इस्तेमाल करने के अनुभव को जितना हो सके उतना आसान बनाया जा सकता है. Python में बिल्ट-इन help() यूटिलिटी का इस्तेमाल करने वाले और हमारे दस्तावेज़ ऑनलाइन ब्राउज़ करने वाले, दोनों ही मामलों में इस नए दस्तावेज़ का आसानी से इस्तेमाल कर सकते हैं.

यहां दिए गए दस्तावेज़ों का सटीक फ़ॉर्मैट बदला जा सकता है क्योंकि यह प्रोजेक्ट आगे बढ़ रहा है. फिर भी, मैंने 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 क्लास में हमारे नए ""टाइप"" दस्तावेज़ को शामिल करने के लिए, लंबे समय तक चलने वाली रणनीति को अपनाने के लिए सबसे सही रणनीति पर सहमत हो जाएगी, तो उदाहरण के लिए Matplotlib बढ़ोतरी प्रपोज़ल 30 में मेरे सुझाए गए तरीके को आसानी से बदला जा सकता है.

आखिर में, Docs के इस Google सीज़न में इंप्लिसिट टाइप की शुरुआती सूची, जिसे मैं दस्तावेज़ के तौर पर दिखाने का सुझाव देता/देती हूं:

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

इस दस्तावेज़ का लाइव वर्शन हमारे चर्चा में देखा जा सकता है.