پروژه Matplotlib

این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.

خلاصه پروژه

سازمان منبع باز:

Matplotlib

نویسنده فنی:

برونوبلتران

نام پروژه:

بهبود قابلیت کشف ویژگی با استانداردسازی اسناد انواع "ضمنی".

طول پروژه:

دویدن طولانی مدت (5 ماه)

شرح پروژه

انگیزه

از لحاظ تاریخی، API matplotlib به شدت بر روی "انواع ضمنی" string-as-enum متکی بوده است. علاوه بر تقلید از API matlab، این رشته‌های پارامتر به کاربر اجازه می‌دهند تا مقادیر غنی معنایی را به‌عنوان آرگومان به توابع matplotlib بدون نیاز به وارد کردن صریح یا پیشوند یک مقدار واقعی enum فقط برای ارسال گزینه‌های نمودار اصلی (یعنی plt.plot(x, y, linestyle='solid') ارسال کند. plt.plot(x, y, linestyle='solid') تایپ کردن آسان‌تر و کمتر از چیزی مانند plt.plot(x, y, linestyle=mpl.LineStyle.solid) است.

بسیاری از این گونه‌های ضمنی رشته‌ای به‌عنوان فهرست از آن زمان ویژگی‌های پیچیده‌تری پیدا کرده‌اند. برای مثال، یک linestyle اکنون می‌تواند یک رشته یا دو تایی از دنباله‌ها باشد، و یک MarkerStyle اکنون می‌تواند یک رشته یا یک matplotlib.path.Path باشد. در حالی که این در مورد بسیاری از انواع ضمنی صدق می کند، MarkerStyle تنها موردی است (تا آنجا که من می دانم) که وضعیت ارتقا به کلاس پایتون مناسب را دارد.

از آنجا که این انواع ضمنی به خودی خود کلاس نیستند، Matplotlib در طول تاریخ مجبور بوده راه حل های خود را برای متمرکز کردن اسناد و اعتبار این انواع ضمنی ارائه دهد (به ترتیب به ترتیب الگوی درون یابی docstring.interpd.update و الگوی اعتبارسنجی cbook._check_in_list . به جای استفاده از زنجیره‌های ابزار استاندارد ارائه شده توسط کلاس‌های پایتون (به‌عنوان مثال، رشته‌های اسناد و الگوی اعتبارسنجی در __init__ ، به ترتیب).

در حالی که این راه حل ها برای ما خوب کار کرده اند، فقدان یک مکان صریح برای مستندسازی هر نوع ضمنی به این معنی است که یافتن اسناد اغلب دشوار است، جداول بزرگی از مقادیر مجاز در سراسر مستندات تکرار می شوند، و اغلب بیانیه ای صریح از محدوده یک نوع ضمنی کاملاً در اسناد وجود ندارد. برای مثال، اسناد plt.plot را در نظر بگیرید: در «یادداشت‌ها»، توضیحی از روش استایل‌بندی رشته‌های قالب مانند matlab به گزینه‌های linestyle ، color و markers اشاره می‌کند. روش‌های بسیار بیشتری برای انتقال این سه مقدار نسبت به آنچه اشاره شده است وجود دارد، اما برای بسیاری از کاربران، این تنها منبع درک آنها از مقادیری است که برای آن گزینه‌ها ممکن است تا زمانی که به یکی از آموزش‌های مربوطه برخورد کنند. جدولی از ویژگی‌های Line2D در تلاشی گنجانده شده است تا به خواننده نشان دهد چه گزینه‌هایی برای کنترل طرح خود دارند. با این حال، در حالی که ورودی linestyle کار خوبی برای پیوند دادن به Line2D.set_linestyle انجام می دهد (دو کلیک لازم است) که در آن ورودی های ممکن توضیح داده شده است، ورودی های color و markers این کار را نمی کنند. color به سادگی به Line2D.set_color پیوند می‌دهد، که نمی‌تواند شهودی برای نوع ورودی‌هایی که حتی مجاز هستند ارائه دهد.

می‌توان گفت که این چیزی است که می‌توان با مرتب کردن رشته‌های مستند فردی که باعث ایجاد مشکل می‌شوند، آن را برطرف کرد، اما متاسفانه موضوع بسیار سیستمیک‌تر از این است. بدون یک مکان متمرکز برای یافتن مستندات، این به سادگی منجر به این می‌شود که ما نسخه‌های بیشتری از اسناد پرمخاطب را در هر جایی که از هر یک از این انواع ضمنی استفاده می‌شود تکرار می‌کنیم، و به ویژه یافتن پارامتر مورد نیاز را برای کاربران مبتدی دشوارتر می‌کند. . با این حال، سیستم فعلی، که کاربران را مجبور می‌کند به آرامی مدل ذهنی خود را از هر نوع ضمنی از طریق پیمایش سبک ویکی غواصی در سراسر مستندات ما، یا تکه‌تکه از نمونه‌های StackOverflow کنار هم قرار دهند، نیز پایدار نیست.

هدف نهایی

در حالت ایده‌آل، هر ذکری از یک نوع ضمنی باید به یک صفحه منفرد پیوند بخورد که تمام مقادیر ممکن را که نوع می‌تواند بگیرد، از ساده‌ترین و رایج‌ترین تا پیشرفته‌ترین یا باطنی‌ترین آن‌ها را توصیف می‌کند. به جای استفاده از فضای بصری ارزشمند در اسناد API سطح بالا برای برشمردن تکه‌ای تمام انواع ورودی ممکن برای یک پارامتر خاص، می‌توانیم از همان فضا برای ارائه توصیفی ساده از انتزاع نموداری که پارامتر برای کنترل آن است استفاده کنیم. .

برای استفاده مجدد از مثال 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. فرآیند کشف ویژگی‌های قدرتمندتر و روش‌های ورودی را برای دیدن گزینه‌های پیشرفته‌تر (هنوز تنها با یک کلیک) به آسانی ""scroll down"" انجام دهید.
5. یک استراتژی متمرکز برای پیوند دادن اسناد سطح بالا "API" به "آموزش‌های" مربوطه ارائه دهید.
6. از API-doc-explosion اجتناب کنید، جایی که اسکن بسیاری از گزینه‌های ممکن برای هر یک از پارامترها باعث می‌شود رشته‌های اسناد فردی ناکارآمد شوند.

سایر مزایای این رویکرد نسبت به اسناد فعلی عبارتند از:

1. اسناد به دلیل متمرکز بودن کمتر احتمال دارد کهنه شوند.
2. متعارف سازی بسیاری از "استانداردهای ضمنی" matplotlib (مانند آنچه ""محدوده ها" در مقابل "گستره ها" است) که در حال حاضر باید با خواندن کد یاد شوند.
3. این فرآیند مشکلات مربوط به سازگاری API را به گونه‌ای برجسته می‌کند که می‌توان به راحتی از طریق ردیاب مسائل GitHub ردیابی کرد و به روند بهبود API ما کمک کرد.
4. زمان ساخت سند سریعتر، به دلیل کاهش قابل توجه در مقدار متنی که نیاز به تجزیه دارد.

پیاده سازی

بهبودهایی که در بالا توضیح داده شد به دو تلاش عمده نیاز دارد که برای آنها یک نویسنده فنی اختصاصی ارزشمند خواهد بود. اولین مورد ایجاد یک صفحه متمرکز "آموزش" در هر نوع ضمنی است. این امر مستلزم همکاری با تیم توسعه‌دهنده اصلی برای شناسایی فهرست مشخصی از انواع ضمنی است که اسناد آنها برای کاربران ارزشمند است (معمولاً، زیرا آنها حاوی ویژگی‌های قدرتمند و پنهان کتابخانه ما هستند که اسناد آن در حال حاضر فقط در مواردی یافت می‌شوند که به سختی می‌توان آنها را گرفتار کرد. در سراسر آموزش). برای هر نوع ضمنی، من آموزش‌های مختلف مرتبط، اسناد API و صفحات نمونه را در یک منبع معتبر از اسناد ترکیب می‌کنم که می‌تواند به هر جایی که به آن نوع خاص ارجاع داده می‌شود پیوند داده شود.

هنگامی که اسناد متمرکز برای یک نوع ضمنی مشخص کامل شد، دومین تلاش اصلی آغاز می‌شود: جایگزینی اسناد API موجود با پیوندهایی به اسناد جدید، با چشم‌اندازی به سمت آسان‌تر کردن تجربه استفاده واقعی از این مستندات جدید، هم برای آن‌ها. با استفاده از ابزار 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`.
""""""

با حرکت رو به جلو، به راحتی می‌توانیم نحوه املای این مراجع را تغییر دهیم، زمانی که تیم توسعه‌دهنده اصلی بر روی بهترین استراتژی بلندمدت برای ترکیب اسناد جدید "انواع" ما در کلاس‌های پایتون با حسن نیت به توافق رسید، به عنوان مثال همانطور که توسط من در 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

نسخه زنده این سند را می توان در گفتمان ما یافت.