Project Matplotlib

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

Ringkasan project

Organisasi open source:
Matplotlib
Penulis teknis:
brunobeltran
Nama project:
Meningkatkan visibilitas fitur dengan menstandarkan dokumentasi jenis “implisit”
Durasi proyek:
Berjalan lama (5 bulan)

Project description

Motivasi

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

Banyak jenis implisit string-as-enum ini yang telah berkembang menjadi fitur yang lebih canggih. Misalnya, linestyle kini dapat berupa string atau tuple 2 urutan, dan MarkerStyle kini dapat berupa string atau matplotlib.path.Path. Meskipun ini berlaku untuk banyak jenis implisit, MarkerStyle adalah satu-satunya (setahu saya) yang memiliki status telah diupgrade ke class Python yang tepat.

Karena jenis implisit ini bukan class tersendiri, 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, masing-masing) daripada menggunakan toolchain standar yang disediakan oleh class Python (misalnya, docstring dan pola validate-at-__init__, masing-masing).

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

Dapat dipastikan bahwa hal ini adalah sesuatu yang dapat diperbaiki hanya dengan merapikan masing-masing dokumen yang menyebabkan masalah, tetapi sayangnya masalahnya, sayangnya, jauh lebih sistemik. Tanpa tempat terpusat untuk menemukan dokumentasi, hal ini hanya akan membuat kita memiliki lebih banyak salinan dokumentasi yang semakin panjang dan diulang di mana pun setiap jenis implisit ini digunakan, sehingga mempersulit pengguna pemula untuk menemukan parameter yang mereka butuhkan. Namun, sistem saat ini, yang memaksa pengguna untuk perlahan-lahan menyusun model mental mereka dari setiap jenis implisit melalui traversal gaya wiki-diving di seluruh dokumentasi kami, atau secara terpisah dari contoh StackOverflow, juga tidak berkelanjutan.

Sasaran Akhir

Idealnya, setiap penyebutan jenis implisit harus ditautkan ke satu halaman yang menjelaskan semua kemungkinan nilai yang dapat diambil jenis tersebut, yang diurutkan dari yang paling sederhana dan umum hingga yang paling canggih atau esoteris. Daripada menggunakan ruang visual yang berharga dalam dokumentasi API tingkat atas untuk menghitung semua kemungkinan jenis input ke parameter tertentu, kita dapat menggunakan ruang yang sama untuk memberikan deskripsi kata-kata sederhana tentang abstraksi plot yang dimaksudkan untuk dikontrol parameter.

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

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

Tampilannya dalam dokumen LineCollection yang sebenarnya hanya 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 di-resolve oleh Sphinx untuk mengarah ke satu kumpulan dokumentasi yang kredibel dan lengkap tentang cara Matplotlib memperlakukan gaya garis.

Manfaat

Beberapa fitur canggih dari pendekatan ini meliputi

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

Manfaat lain dari pendekatan ini dibandingkan dengan dokumen saat ini adalah:

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

Penerapan

Peningkatan yang dijelaskan di atas akan memerlukan dua upaya utama yang sangat penting 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 bernilai bagi pengguna (biasanya, karena berisi fitur tersembunyi yang canggih dari library kami yang dokumentasinya saat ini hanya ditemukan dalam tutorial yang sulit ditemukan). Untuk setiap jenis implisit, saya akan menyingkat berbagai tutorial, dokumen API, dan halaman contoh yang relevan menjadi satu sumber dokumentasi resmi yang dapat ditautkan ke mana saja 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 mempermudah pengalaman penggunaan dokumentasi baru ini menjadi semudah mungkin, baik bagi mereka yang menggunakan utilitas help() bawaan Python maupun bagi mereka yang menjelajahi dokumentasi kami secara online.

Meskipun format dokumentasi yang tepat yang diusulkan di sini dapat berubah seiring perkembangan project ini, saya telah bekerja sama dengan tim inti Matplotlib selama ""panggilan developer"" mingguan mereka untuk membangun konsensus bahwa strategi yang diusulkan di sini adalah pendekatan yang paling cepat, berguna, dan dapat ditangani secara teknis untuk mulai mendokumentasikan ""jenis implisit"" ini (catatan tentang panggilan ini tersedia di hackmd). Saya akan menggunakan infrastruktur ""tutorial"" yang sudah ada untuk tahap awal pembuatan dokumentasi terpusat untuk setiap jenis implisit, sehingga saya dapat dengan mudah merujuk 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`.
""""""

Ke depannya, kita dapat dengan mudah mengubah cara penulisan referensi ini setelah tim developer inti menyetujui strategi jangka panjang terbaik untuk memasukkan dokumentasi ""types"" baru ke dalam class Python yang sah, misalnya seperti yang saya usulkan dalam Matplotlib Enhancement Proposal 30.

Terakhir, daftar awal jenis implisit yang saya sarankan untuk didokumentasikan selama Google Season of Docs ini adalah:

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

Versi terbaru dokumen ini dapat ditemukan di Diskusi kami.