Project Matplotlib

Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.

Ringkasan proyek

Organisasi open source:
Matplotlib
Penulis teknis:
brunobeltran
Nama proyek:
Meningkatkan visibilitas fitur dengan menstandardisasi dokumentasi jenis “implisit”
Durasi proyek:
Jangka panjang (5 bulan)

Project description

Motivasi

Secara historis, API matplotlib sangat bergantung pada ""jenis implisit" string-as-enum". Selain meniru API matlab, string parameter ini memungkinkan pengguna meneruskan nilai yang kaya secara semantik sebagai argumen ke fungsi matplotlib tanpa harus mengimpor secara eksplisit atau secara panjang mengawali nilai enum yang sebenarnya hanya untuk meneruskan opsi plot dasar (yaitu plt.plot(x, y, linestyle='solid') lebih mudah diketik dan tidak terlalu berlebihan dibandingkan plt.plot(x, y, linestyle=mpl.LineStyle.solid)).

Banyak dari jenis implisit string-sebagai enum ini kemudian mengembangkan fitur yang lebih canggih. Misalnya, linestyle sekarang dapat berupa string atau 2 tuple urutan, dan MarkerStyle sekarang dapat berupa string atau matplotlib.path.Path. Meskipun ini berlaku untuk banyak jenis implisit, MarkerStyle adalah satu-satunya (sepengetahuan saya) yang berstatus telah diupgrade ke class Python yang tepat.

Karena jenis implisit ini bukan class dengan haknya sendiri, Matplotlib secara historis harus meluncurkan solusinya sendiri untuk memusatkan dokumentasi dan validasi jenis implisit ini (misalnya, pola interpolasi docstring docstring.interpd.update dan pola validator cbook._check_in_list), bukan menggunakan toolchain standar yang disediakan oleh class Python (misalnya docstring dan pola validasi pada __init__).

Meskipun solusi ini telah bekerja dengan baik bagi kami, kurangnya lokasi eksplisit untuk mendokumentasikan setiap jenis implisit berarti bahwa dokumentasi sering kali sulit ditemukan, tabel besar dengan nilai yang diizinkan diulang di seluruh dokumentasi, dan sering kali pernyataan eksplisit cakupan jenis implisit sama sekali tidak ada di dokumen. Ambil dokumen plt.plot, misalnya: dalam ""Notes", deskripsi metode penataan gaya string format seperti matlab menyebutkan opsi linestyle, color, dan markers. Ada banyak cara lain untuk meneruskan ketiga nilai ini selain yang disebutkan, tetapi bagi banyak pengguna, ini adalah satu-satunya sumber pemahaman tentang nilai yang mungkin untuk opsi tersebut sampai mereka menemukan salah satu tutorial yang relevan. Tabel atribut Line2D disertakan dalam upaya untuk menunjukkan kepada pembaca opsi yang mereka miliki untuk mengontrol plotnya. Namun, meskipun entri linestyle dapat menautkan ke Line2D.set_linestyle dengan baik (diperlukan dua klik) saat kemungkinan input dijelaskan, entri color dan markers tidak. color hanya menautkan ke Line2D.set_color, yang gagal menawarkan intuisi untuk jenis input apa yang bahkan diizinkan.

Dapat dipastikan bahwa masalah ini dapat diperbaiki hanya dengan merapikan setiap docstring yang menyebabkan masalah, tetapi sayangnya masalah ini jauh lebih sistematis dari itu. Tanpa tempat terpusat untuk menemukan dokumentasi, kami hanya akan membuat lebih banyak salinan dokumentasi yang semakin panjang diulang di mana pun setiap jenis implisit ini digunakan, sehingga menyulitkan pengguna pemula untuk hanya menemukan parameter yang mereka butuhkan. Namun, sistem saat ini, yang memaksa pengguna untuk perlahan-lahan menggabungkan model mental mereka dari setiap jenis implisit melalui traversal gaya wiki-diving di seluruh dokumentasi kami, atau potongan-potongan kecil dari contoh StackOverflow, juga tidak berkelanjutan.

Sasaran Akhir

Idealnya, setiap penyebutan jenis implisit harus tertaut ke satu halaman yang menjelaskan semua kemungkinan nilai yang dapat diambil jenis tersebut, diurutkan dari yang paling sederhana dan umum hingga yang paling canggih atau esoterik. Daripada menggunakan ruang visual yang berharga dalam dokumentasi API level atas untuk secara bertahap menghitung semua kemungkinan jenis input untuk parameter tertentu, kita kemudian dapat menggunakan ruang yang sama tersebut untuk memberikan deskripsi sederhana tentang plot abstraksi yang ingin dikontrol oleh parameter.

Untuk menggunakan contoh linestyle lagi, yang kita inginkan dalam dokumen LineCollection hanyalah:

  1. Link untuk menyelesaikan dokumen untuk input yang diizinkan (kombinasi yang ditemukan dalam Line2D.set_linestyle dan tutorial linestyle).
  2. Deskripsi kata-kata sederhana tentang tujuan parameter. Untuk pengguna super matplotlib, hal ini terlihat dari nama parameter, tetapi tidak perlu bagi pengguna baru.

Tampilannya dalam dokumen LineCollection yang sebenarnya hanyalah 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. """""" dengan referensi jenis LineStyle akan diselesaikan oleh Sphinx untuk mengarah ke satu set dokumentasi yang otoritatif dan lengkap terkait cara Matplotlib memperlakukan linestyle.

Manfaat

Beberapa fitur ampuh dari pendekatan ini antara lain

  1. Memahami kemampuan setiap fungsi secara lengkap dalam teks biasa (tidak memerlukan klik).
  2. Membuat opsi default terlihat (tanpa klik). Melihat opsi default sering kali cukup untuk mengenang pengguna yang kembali.
  3. Buat deskripsi lengkap tentang opsi ""paling umum"" dan ""termudah"" untuk parameter yang mudah tersedia saat menjelajah (dengan sekali klik).
  4. Buat proses untuk menemukan fitur dan metode input yang lebih canggih semudah ""scroll ke bawah"" untuk melihat opsi lanjutan lainnya (hanya dengan sekali klik).
  5. Memberikan strategi terpusat untuk menautkan dokumen ""API"" tingkat atas ke ""tutorial" yang relevan".
  6. Hindari API-doc-explosion, karena memindai berbagai kemungkinan opsi untuk setiap parameter akan membuat setiap docstring sulit.

Manfaat lain dari pendekatan ini dibandingkan dokumen saat ini adalah:

  1. Dokumen cenderung tidak menjadi usang karena adanya sentralisasi.
  2. Kanonikalisasi banyak ""standar implisit"" matplotlib (seperti yang dimaksud dengan ""batas"" versus ""luas"") yang saat ini harus dipelajari dengan membaca kode.
  3. Proses ini akan menyoroti masalah terkait konsistensi API dengan cara yang dapat lebih mudah dilacak melalui pelacak masalah GitHub, sehingga membantu proses peningkatan API kami.
  4. Waktu build dokumen menjadi lebih cepat karena penurunan jumlah teks yang perlu diurai secara signifikan.

Penerapan

Peningkatan yang dijelaskan di atas akan memerlukan dua upaya besar yang akan sangat berharga bagi penulis teknis khusus. Yang pertama adalah membuat satu halaman ""tutorial"" terpusat per jenis implisit. Hal ini akan memerlukan kerja sama dengan tim developer inti untuk mengidentifikasi daftar konkret jenis implisit yang dokumentasinya akan berharga bagi pengguna (biasanya, karena berisi fitur library kami yang canggih dan tersembunyi, yang dokumentasinya saat ini hanya ditemukan dalam tutorial yang sulit ditemukan). Untuk setiap jenis implisit, saya akan menyintesis berbagai tutorial, dokumen API, dan halaman contoh yang relevan ke dalam satu sumber dokumentasi resmi yang dapat ditautkan ke mana pun jenis tertentu tersebut dirujuk.

Setelah dokumentasi terpusat untuk jenis implisit tertentu selesai, upaya besar kedua dimulai: mengganti dokumentasi API yang ada dengan link ke dokumentasi baru, dengan tujuan menjadikan pengalaman benar-benar menggunakan dokumentasi baru ini semudah mungkin, baik bagi mereka yang menggunakan utilitas help() bawaan Python dan mereka yang menjelajahi dokumentasi kami secara online.

Meskipun format persis dokumentasi yang diusulkan di sini dapat berubah seiring perkembangan project ini, saya telah bekerja sama dengan tim inti Matplotlib selama ""panggilan dev"" mingguan mereka untuk menetapkan konsensus bahwa strategi yang diusulkan di sini adalah pendekatan yang paling tepat, berguna, dan bisa direspons secara teknis untuk mulai mendokumentasikan ""jenis implisit"" ini (catatan tentang callmd ini tersedia). Saya akan menggunakan infrastruktur ""tutorial"" yang ada untuk tahap awal pembuatan dokumentasi terpusat untuk setiap jenis implisit, sehingga saya dapat dengan mudah mereferensikan halaman ini sebagai berikut, tanpa harus membuat class publik baru (sekali lagi, menggunakan dokumen LineCollection sebagai contoh):

""""""
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`.
""""""

Selanjutnya, kami dapat dengan mudah mengubah cara ejaan referensi ini setelah tim developer inti menyetujui strategi jangka panjang terbaik untuk menggabungkan dokumentasi ""jenis"" baru kami ke dalam class Python yang bonafide, misalnya seperti yang saya usulkan dalam Proposal Penyempurnaan Masthead 30.

Terakhir, daftar awal jenis implisit yang saya usulkan untuk dokumentasi selama Google Season Dokumen ini adalah:

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

Versi aktif dokumen ini dapat ditemukan di Discourse kami.