Matplotlib प्रोजेक्ट

इस पेज पर, तकनीकी लेखन वाले उस प्रोजेक्ट की जानकारी दी गई है जिसे Google Season of Docs के लिए स्वीकार किया गया है.

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

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

Matplotlib

टेक्निकल राइटर:

brunobeltran

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

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

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

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

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

वजह

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

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

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

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

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

आखिरी लक्ष्य

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

linestyle के उदाहरण का फिर से इस्तेमाल करने के लिए, हमें LineCollection दस्तावेज़ों में सिर्फ़ यह चाहिए:

1. अनुमति दिए जा सकने वाले इनपुट के लिए, दस्तावेज़ों को पूरा करने का लिंक. यह लिंक, Line2D.set_linestyle और 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. """""" LineStyle टाइप रेफ़रंस को Sphinx हल करेगा. इससे, Matplotlib के लाइनस्टाइल के इस्तेमाल के बारे में, एक आधिकारिक और पूरे दस्तावेज़ के सेट पर पहुंचा जा सकेगा.

फ़ायदे

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

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

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

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

लागू करना

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

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

इस प्रोजेक्ट के आगे बढ़ने के साथ-साथ, यहां सुझाए गए दस्तावेज़ का सटीक फ़ॉर्मैट बदल सकता है. मैंने 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

इस दस्तावेज़ का अप-टू-डेट वर्शन, हमारे डिस्कॉर्स पर देखा जा सकता है.