এই পৃষ্ঠায় Google সিজন অফ ডক্সের জন্য গৃহীত প্রযুক্তিগত লেখার প্রকল্পের বিশদ বিবরণ রয়েছে৷
প্রকল্পের সারসংক্ষেপ
- ওপেন সোর্স সংস্থা:
- ম্যাটপ্লটলিব
- কৌশলী লেখক:
- ব্রুনোবেলট্রান
- প্রকল্পের নাম:
- "অন্তর্নিহিত" প্রকারের ডকুমেন্টেশনকে মানসম্মত করে বৈশিষ্ট্য আবিষ্কারযোগ্যতা উন্নত করা
- প্রকল্পের দৈর্ঘ্য:
- দীর্ঘ চলমান (5 মাস)
প্রকল্প বর্ণনা
প্রেরণা
ঐতিহাসিকভাবে, matplotlib-এর API স্ট্রিং-অ্যাস-এনাম ""অন্তর্ভুক্ত প্রকার"-এর উপর অনেক বেশি নির্ভর করে। ম্যাটল্যাবের এপিআই নকল করার পাশাপাশি, এই প্যারামিটার-স্ট্রিংগুলি ব্যবহারকারীকে matplotlib ফাংশনে আর্গুমেন্ট হিসাবে শব্দার্থ-সমৃদ্ধ মানগুলিকে স্পষ্টভাবে আমদানি না করে বা শব্দাত্মকভাবে একটি প্রকৃত enum মানকে শুধুমাত্র মৌলিক প্লট বিকল্পগুলি পাস করার জন্য পাস করার অনুমতি দেয় (যেমন plt.plot(x, y, linestyle='solid') টাইপ করা সহজ এবং plt.plot(x, y, linestyle=mpl.LineStyle.solid) এর মতো কিছুর চেয়ে কম অপ্রয়োজনীয়।
এই স্ট্রিং-এ-এনাম অন্তর্নিহিত প্রকারগুলির মধ্যে অনেকগুলি তখন থেকে আরও পরিশীলিত বৈশিষ্ট্যগুলি বিকাশ করেছে। উদাহরণস্বরূপ, একটি linestyle এখন হয় একটি স্ট্রিং বা 2-টুপল সিকোয়েন্স হতে পারে এবং একটি মার্কারস্টাইল এখন একটি স্ট্রিং বা একটি matplotlib.path.Path হতে পারে। যদিও এটি অনেক অন্তর্নিহিত প্রকারের ক্ষেত্রে সত্য, মার্কারস্টাইলই একমাত্র (আমার জানামতে) যা একটি সঠিক পাইথন ক্লাসে আপগ্রেড হওয়ার স্থিতি পেয়েছে।
যেহেতু এই অন্তর্নিহিত প্রকারগুলি তাদের নিজস্ব শ্রেণী নয়, তাই ম্যাটপ্লটলিবকে ঐতিহাসিকভাবে ডকুমেন্টেশন কেন্দ্রীকরণ এবং এই অন্তর্নিহিত প্রকারগুলির বৈধতার জন্য নিজস্ব সমাধানগুলি রোল করতে হয়েছে (যেমন docstring.interpd.update ডকস্ট্রিং ইন্টারপোলেশন প্যাটার্ন এবং cbook._check_in_list ভ্যালিডেটর প্যাটার্ন, যথাক্রমে ) এর পরিবর্তে পাইথন ক্লাসের দ্বারা প্রদত্ত স্ট্যান্ডার্ড টুলচেইন ব্যবহার করে (যেমন ডকস্ট্রিং এবং যথাক্রমে validate-at- __init__ প্যাটার্ন)।
যদিও এই সমাধানগুলি আমাদের জন্য ভাল কাজ করেছে, প্রতিটি অন্তর্নিহিত প্রকারের নথিভুক্ত করার জন্য একটি সুস্পষ্ট অবস্থানের অভাবের অর্থ হল ডকুমেন্টেশনটি প্রায়শই খুঁজে পাওয়া কঠিন, অনুমোদিত মানের বড় টেবিলগুলি ডকুমেন্টেশন জুড়ে পুনরাবৃত্তি হয় এবং প্রায়শই এর সুযোগের একটি সুস্পষ্ট বিবৃতি। একটি অন্তর্নিহিত প্রকার ডক্স থেকে সম্পূর্ণরূপে অনুপস্থিত. plt.plot ডক্স নিন, উদাহরণস্বরূপ: ""নোটস"-এ, ম্যাটল্যাব-এর মতো ফরম্যাট-স্ট্রিং স্টাইলিং পদ্ধতির একটি বিবরণ linestyle , color এবং markers বিকল্পগুলি উল্লেখ করে৷ এই তিনটি মান পাস করার জন্য ইঙ্গিত করার চেয়ে আরও অনেক উপায় আছে, কিন্তু অনেক ব্যবহারকারীর জন্য, প্রাসঙ্গিক টিউটোরিয়ালগুলির একটিতে হোঁচট না খাওয়া পর্যন্ত এই বিকল্পগুলির জন্য কোন মানগুলি সম্ভব তা বোঝার এটিই একমাত্র উৎস। Line2D বৈশিষ্ট্যগুলির একটি টেবিল পাঠককে দেখানোর জন্য তাদের প্লট নিয়ন্ত্রণের জন্য কী বিকল্প রয়েছে তা অন্তর্ভুক্ত করা হয়েছে। যাইহোক, যদিও linestyle এন্ট্রি Line2D.set_linestyle লিঙ্ক করার জন্য একটি ভাল কাজ করে (দুটি ক্লিক প্রয়োজন) যেখানে সম্ভাব্য ইনপুটগুলি বর্ণনা করা হয়েছে, color এবং markers এন্ট্রিগুলি তা করে না। color সহজভাবে Line2D.set_color এর সাথে লিঙ্ক করে, যা কোন ধরনের ইনপুট এমনকি অনুমোদিত হয় তার জন্য কোনো অন্তর্দৃষ্টি দিতে ব্যর্থ হয়।
এটি যুক্তি দেওয়া যেতে পারে যে এটি এমন কিছু যা সমস্যা সৃষ্টিকারী পৃথক ডকস্ট্রিংগুলিকে পরিষ্কার করে ঠিক করা যেতে পারে, তবে সমস্যাটি দুর্ভাগ্যবশত এর চেয়ে অনেক বেশি পদ্ধতিগত। ডকুমেন্টেশন খোঁজার জন্য একটি কেন্দ্রীভূত স্থান ছাড়াই, এটি আমাদেরকে ক্রমবর্ধমান ভার্বোস ডকুমেন্টেশনের আরও বেশি সংখ্যক অনুলিপির দিকে নিয়ে যাবে যেখানে এই সমস্ত অন্তর্নিহিত প্রকারগুলি ব্যবহার করা হয়, যার ফলে নতুন ব্যবহারকারীদের জন্য তাদের প্রয়োজনীয় প্যারামিটার খুঁজে পাওয়া বিশেষত আরও কঠিন হয়ে ওঠে। . যাইহোক, বর্তমান সিস্টেম, যা ব্যবহারকারীদের আমাদের ডকুমেন্টেশন জুড়ে উইকি-ডাইভিং স্টাইল ট্রাভার্সাল বা স্ট্যাকওভারফ্লো উদাহরণ থেকে টুকরো টুকরো টুকরো টুকরো করে প্রতিটি অন্তর্নিহিত ধরণের মানসিক মডেলকে ধীরে ধীরে একত্রিত করতে বাধ্য করে, তাও টেকসই নয়।
শেষ লক্ষ্য
আদর্শভাবে, একটি অন্তর্নিহিত প্রকারের যেকোন উল্লেখ একটি একক পৃষ্ঠার সাথে লিঙ্ক করা উচিত যা টাইপ গ্রহণ করতে পারে এমন সমস্ত সম্ভাব্য মান বর্ণনা করে, সবচেয়ে সাধারণ এবং সাধারণ থেকে সবচেয়ে উন্নত বা গুপ্ত পর্যন্ত অর্ডার করা। একটি নির্দিষ্ট প্যারামিটারে সমস্ত সম্ভাব্য ইনপুট প্রকারগুলিকে টুকরো টুকরো করে গণনা করার জন্য শীর্ষ-স্তরের API ডকুমেন্টেশনে মূল্যবান ভিজ্যুয়াল স্পেস ব্যবহার করার পরিবর্তে, প্যারামিটারটি নিয়ন্ত্রণ করার জন্য কী প্লটিং বিমূর্ততা বোঝায় তার একটি সরল-শব্দ বর্ণনা দিতে আমরা সেই একই স্থান ব্যবহার করতে পারি। .
linestyle উদাহরণটি আবার ব্যবহার করতে, আমরা LineCollection ডক্সে যা চাই তা হল:
- অনুমোদনযোগ্য ইনপুটগুলির জন্য ডক্স সম্পূর্ণ করার একটি লিঙ্ক (
Line2D.set_linestyleএবং লাইনস্টাইল টিউটোরিয়াল এ পাওয়া যায় এমন একটি সংমিশ্রণ)। - প্যারামিটারটি সম্পন্ন করার জন্য কী বোঝানো হয়েছে তার একটি সরল শব্দের বর্ণনা। 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 টাইপ রেফারেন্সটি স্ফিংস দ্বারা সমাধান করা হবে যাতে ম্যাটপ্লটলিব লাইনস্টাইলগুলির সাথে কীভাবে আচরণ করে তার জন্য একক, প্রামাণিক এবং সম্পূর্ণ ডকুমেন্টেশনের সেটের দিকে নির্দেশ করে।
সুবিধা
এই পদ্ধতির কিছু শক্তিশালী বৈশিষ্ট্য অন্তর্ভুক্ত
- প্রতিটি ফাংশন প্লেইন টেক্সটে সুস্পষ্ট করতে সক্ষম তার সম্পূর্ণ পরিমাণ তৈরি করা (শূন্য ক্লিকের প্রয়োজনে)।
- ডিফল্ট বিকল্পটি দৃশ্যমান করা (শূন্য ক্লিকের সাথে)। ডিফল্ট বিকল্প দেখা প্রায়ই ফিরে আসা ব্যবহারকারীদের মেমরি জগ করার জন্য যথেষ্ট।
- ব্রাউজ করার সময় সহজে উপলব্ধ একটি প্যারামিটারের জন্য ""সবচেয়ে সাধারণ"" এবং ""সবচেয়ে সহজ" বিকল্পগুলির একটি সম্পূর্ণ বিবরণ তৈরি করুন (একটি ক্লিকে)।
- আরও উন্নত বিকল্পগুলি দেখতে (এখনও শুধুমাত্র একটি ক্লিকে) আরও শক্তিশালী বৈশিষ্ট্য এবং ইনপুট পদ্ধতিগুলি আবিষ্কার করার প্রক্রিয়াটিকে ""স্ক্রোল ডাউন"" এর মতো সহজ করুন৷
- প্রাসঙ্গিক ""টিউটোরিয়াল" এর সাথে শীর্ষ-স্তরের ""API"" ডক্স লিঙ্ক করার জন্য একটি কেন্দ্রীভূত কৌশল প্রদান করুন।
- এপিআই-ডক-বিস্ফোরণ এড়িয়ে চলুন, যেখানে প্রতিটি প্যারামিটারে অনেকগুলি সম্ভাব্য বিকল্পের মাধ্যমে স্ক্যান করা স্বতন্ত্র ডকস্ট্রিংগুলিকে অপ্রতিরোধ্য করে তোলে।
বর্তমান ডক্সে এই পদ্ধতির অন্যান্য সুবিধা হল:
- কেন্দ্রীকরণের কারণে ডক্স বাসি হওয়ার সম্ভাবনা কম।
- ম্যাটপ্লটলিবের অনেকগুলি ""অন্তর্নিহিত মান" (যেমন ""সীমা"" বনাম ""ব্যাপ্তি"") এর ক্যানোনিকালাইজেশন যা বর্তমানে কোডটি পড়ে শিখতে হবে।
- প্রক্রিয়াটি API সামঞ্জস্যের সমস্যাগুলিকে এমনভাবে হাইলাইট করবে যা GitHub সমস্যা ট্র্যাকারের মাধ্যমে আরও সহজে ট্র্যাক করা যেতে পারে, আমাদের API উন্নত করার প্রক্রিয়াতে সহায়তা করে।
- পার্স করার জন্য প্রয়োজনীয় পাঠ্যের পরিমাণ উল্লেখযোগ্য হ্রাসের কারণে দ্রুত ডক তৈরির সময়।
বাস্তবায়ন
উপরে বর্ণিত উন্নতিগুলির জন্য দুটি বড় প্রচেষ্টার প্রয়োজন হবে যার জন্য একজন নিবেদিত প্রযুক্তিগত লেখক অমূল্য হবে। প্রথমটি হল প্রতি অন্তর্নিহিত প্রকারের জন্য একটি কেন্দ্রীভূত ""টিউটোরিয়াল"" পৃষ্ঠা তৈরি করা। এর জন্য মূল বিকাশকারী দলের সাথে কাজ করতে হবে অন্তর্নিহিত ধরণের একটি কংক্রিট তালিকা সনাক্ত করতে যার ডকুমেন্টেশনগুলি ব্যবহারকারীদের জন্য মূল্যবান হবে (সাধারণত, কারণ এতে আমাদের লাইব্রেরির শক্তিশালী, লুকানো বৈশিষ্ট্য রয়েছে যার ডকুমেন্টেশন বর্তমানে শুধুমাত্র কঠিন-থেকে-হঠাৎ পাওয়া যায়- টিউটোরিয়াল জুড়ে)। প্রতিটি অন্তর্নিহিত প্রকারের জন্য, আমি তারপরে বিভিন্ন প্রাসঙ্গিক টিউটোরিয়াল, API ডক্স এবং উদাহরণ পৃষ্ঠাগুলিকে ডকুমেন্টেশনের একটি একক প্রামাণিক উত্সে সংশ্লেষিত করব যা নির্দিষ্ট ধরণের উল্লেখ করা হয়েছে এমন যে কোনও জায়গায় লিঙ্ক করা যেতে পারে৷
প্রদত্ত অন্তর্নিহিত ধরণের জন্য কেন্দ্রীভূত ডকুমেন্টেশন সম্পূর্ণ হয়ে গেলে, দ্বিতীয় প্রধান প্রচেষ্টা শুরু হয়: বিদ্যমান API ডকুমেন্টেশনকে নতুন ডকুমেন্টেশনের লিঙ্কগুলির সাথে প্রতিস্থাপন করা, বাস্তবে এই নতুন ডকুমেন্টেশনটি যতটা সম্ভব সহজভাবে ব্যবহার করার অভিজ্ঞতা তৈরি করার দিকে নজর দিয়ে, উভয়ের জন্য পাইথনের বিল্ট-ইন help() ইউটিলিটি ব্যবহার করে এবং যারা অনলাইনে আমাদের ডকুমেন্টেশন ব্রাউজ করছেন তাদের জন্য।
যদিও এখানে প্রস্তাবিত ডকুমেন্টেশনের সঠিক বিন্যাসটি এই প্রকল্পটি বিকশিত হওয়ার সাথে সাথে পরিবর্তন সাপেক্ষে, আমি তাদের সাপ্তাহিক ""দেব কল" এর সময় ম্যাটপ্লটলিব কোর টিমের সাথে কাজ করেছি যাতে একটি ঐকমত্য প্রতিষ্ঠা করা যায় যে এখানে প্রস্তাবিত কৌশলটি সবচেয়ে সমীচীন, দরকারী। , এবং এই ""অন্তর্নিহিত প্রকারগুলি"" নথিভুক্ত করা শুরু করার জন্য প্রযুক্তিগতভাবে সংযত পদ্ধতি (এই কলগুলির নোটগুলি 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`.
""""""
এগিয়ে চলুন, আমরা তখন সহজেই পরিবর্তন করতে পারি যে এই রেফারেন্সগুলি কীভাবে বানান করা হয় যখন মূল বিকাশকারী দল আমাদের নতুন ""টাইপস"" ডকুমেন্টেশনকে বাস্তবসম্মত পাইথন ক্লাসে অন্তর্ভুক্ত করার জন্য সর্বোত্তম দীর্ঘমেয়াদী কৌশলে সম্মত হয়, উদাহরণস্বরূপ ম্যাটপ্লটলিবে আমার দ্বারা প্রস্তাবিত। বর্ধিতকরণ প্রস্তাব 30 ।
অবশেষে, এই Google সিজন অফ ডক্সের সময় আমি যে অন্তর্নিহিত প্রকারের নথিপত্রের প্রস্তাব করছি তার প্রাথমিক তালিকা হল:
-
capstyle -
joinstyle -
bounds -
extents -
linestyle -
colors/lists of colors -
colornorm/colormap -
tick formatters
এই নথির একটি জীবন্ত সংস্করণ আমাদের ডিসকোর্সে পাওয়া যাবে।