Matplotlib प्रोजेक्ट

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

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

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

मैटप्लोटलिब

तकनीकी लेखक:

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

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

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

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

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

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

वजह

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

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

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

इन तरीकों ने हमारे लिए काफ़ी मदद की है. फिर भी, हर इंप्लिसिट टाइप को दर्ज करने के लिए किसी खास जगह की जानकारी न होने का मतलब है कि दस्तावेज़ों को ढूंढना अक्सर मुश्किल होता है. साथ ही, पूरे दस्तावेज़ में स्वीकार की गई वैल्यू की बड़ी टेबल दोहराई जाती हैं. साथ ही, अक्सर किसी इंप्लिसिट टाइप के स्कोप की साफ़ तौर पर जानकारी, दस्तावेज़ों में मौजूद नहीं होती. plt.plot दस्तावेज़ लें, जैसे कि: ""Notes"" में मैटलैब जैसी फ़ॉर्मैट-स्ट्रिंग शैली की जानकारी में 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 टाइप के रेफ़रंस को स्फ़िंक्स किसी एक, प्रामाणिक, और दस्तावेज़ों के पूरे सेट की तरफ़ ले जाएगा. इससे यह पता चलेगा कि Matplotlib लाइनस्टाइल को कैसे मैनेज करता है.

फ़ायदे

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

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 में बताया है.

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

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

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