Matplotlib projesi

Bu sayfa, Google Dokümanlar Sezonu için kabul edilen teknik yazı projesinin ayrıntılarını içerir.

Proje özeti

Açık kaynak kuruluşu:
Matplotlib
Teknik yazar:
brunobeltra
Proje adı:
"Dolaylı" türleri içeren belgeleri standart hale getirerek özellik bulunabilirliğini artırma
Proje süresi:
Uzun süreli (5 ay)

Proje açıklaması

Motivasyon

Geçmişte matplotlib'in API'si, ağırlıklı olarak enum olarak dize ("implicit tür") kullanıyordu. Bu parametre dizeleri, matlab'in API'sini taklit etmenin yanı sıra kullanıcının, temel grafik seçeneklerini geçirmek için gerçek bir enum değerini açık bir şekilde içe aktarmak veya ayrıntılı bir şekilde öne çıkarmak zorunda kalmadan, matplotlib işlevlerine semantik olarak zengin değerleri bağımsız değişken olarak iletmesine olanak tanır (yani, plt.plot(x, y, linestyle='solid') yazılması daha kolaydır ve plt.plot(x, y, linestyle=mpl.LineStyle.solid) gibi bir koda göre daha az gereksizdir).

Bu enum olarak dize örtülü türlerinin çoğu o zamandan beri daha gelişmiş özellikler geliştirmiştir. Örneğin, linestyle artık bir dize veya 2 unsurdan oluşan bir dizi olabilir. MarkerStyle artık bir dize veya matplotlib.path.Path olabilir. Bu, birçok örtülü tür için geçerli olsa da (bildiğim kadarıyla) doğru bir Python sınıfına yükseltilmiş olan tek tür MarkerStyle.

Bu örtülü türler kendi başlarına sınıf olmadıklarından Matplotlib, bu örtülü türlerin belgelenmesi ve doğrulanması için geçmişten beri kendi çözümlerini sunmak zorundaydı (ör. sırasıyla docstring.interpd.update docstring interpolasyon modeli ve sırasıyla cbook._check_in_list doğrulayıcı modeli), Python sınıfları tarafından sağlanan standart araç zincirlerini (ör. docatrestring) kullanmak yerine.__init__

Bu çözümler işe yaramış olsa da her örtülü türü belgeleyecek açık bir konumun olmaması belgeleri bulmanın genellikle zor olduğu anlamına gelir. Belgeler boyunca izin verilen değer tablolarının tekrarlanması ve çoğu zaman belgelerde, örtülü bir kapsama dair açık bir ifadenin hiçbir şekilde gösterilmemesi anlamına gelir. Örneğin, plt.plot belgelerini ele alalım: "Notlar" içinde, matlab benzeri biçim-dizesi stil yönteminin açıklamasında linestyle, color ve markers seçenekleri yer almaktadır. Bu üç değeri iletmenin, ipucu verilenden çok daha fazla yolu vardır ancak çoğu kullanıcı için, alakalı eğiticilerden birini bulana kadar bu seçenekler için hangi değerlerin mümkün olduğunu anlamanın tek kaynağı budur. Okuyucuya, grafiklerini kontrol etmek için hangi seçeneklere sahip olduğunu göstermek amacıyla Line2D özellikleri tablosu eklenir. Bununla birlikte, linestyle girişi, olası girişlerin açıklandığı durumlarda Line2D.set_linestyle ile bağlantı oluşturmada iyi iş çıkarsa (iki tıklama gerekir) color ve markers girişleri bunu yapmaz. color basitçe Line2D.set_color öğesine bağlantı verir. Bu da ne tür girişlere izin verildiği konusunda herhangi bir sezgi sağlayamaz.

Bunun, sorunlara neden olan doküman dizelerini ortadan kaldırarak düzeltilebileceği iddia edilebilir, ancak sorun ne yazık ki bundan çok daha sistematiktir. Belgeleri bulabileceğiniz merkezi bir yer olmadığında, bu örtülü türlerin her birinin kullanıldığı her yerde gittikçe daha fazla sayıda ayrıntılı belge kopyası olur ve bu da yeni başlayan kullanıcıların ihtiyaç duydukları parametreyi kolayca bulmasını zorlaştırır. Bununla birlikte, kullanıcıları dokümanlarımızda wiki dalış stilinde geçiş yoluyla veya StackOverflow örneklerinden parça parça yaparak her örtülü türden zihinsel modellerini yavaş yavaş bir araya getirmeye zorlayan mevcut sistem de sürdürülebilir değil.

Son Hedef

İdeal olarak, örtülü bir türden bahsedildiğinde, söz konusu türün alabileceği tüm olası değerleri en basit ve yaygından en gelişmiş ya da en gelişmiş veya ezoterik düzene doğru sıralanmış şekilde açıklayan tek bir sayfaya bağlantı verilmelidir. Olası tüm giriş türlerini belirli bir parametreye göre numaralandırmak için üst düzey API belgelerinde değerli görsel alan kullanmak yerine, aynı alanı parametrenin grafiğe çizdiği soyutlamanın neyi kontrol etmesi gerektiğiyle ilgili sade bir açıklamada yer vermek için kullanabiliriz.

linestyle örneğini tekrar kullanırsak LineCollection dokümanlarında şu şekilde olmasını isteriz:

  1. İzin verilen girişler için belgeleri tamamlama bağlantısı (Line2D.set_linestyle ve çizgi stili eğiticisinde bulunanların bir kombinasyonu).
  2. Parametrenin neyi hedeflediğini açıklayan basit bir açıklama. Matplotlib deneyimli kullanıcıları için bu, parametrenin adından da anlaşılabilir, ancak yeni kullanıcılar için böyle olması gerekmez.

Asıl LineCollection dokümanlarda bu durum 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. """""" burada LineStyle tür referansı, Matplotlib'in çizgi stillerini nasıl işlediğine ilişkin tek, yetkili ve eksiksiz bir belgelere işaret etmek üzere Sfenks tarafından çözülür.

Avantajları

Bu yaklaşımın güçlü özelliklerinden bazıları şunlardır:

  1. Düz metinde her bir işlevin neleri açıkça gösterebileceğini tüm yönleriyle açıklama (sıfır tıklamayla).
  2. Varsayılan seçeneği görünür hale getirme (sıfır tıklamayla). Varsayılan seçeneği görmek, genellikle geri gelen kullanıcıların anılarını hareket ettirmek için yeterlidir.
  3. Göz atarken bir parametreye ilişkin ""en yaygın"" ve ""en kolay"" seçeneklerini tam olarak açıklayın (tek tıklamayla).
  4. Daha gelişmiş seçenekleri (hâlâ tek tıklamayla) görmek için daha güçlü özellikleri ve giriş yöntemlerini keşfetme işlemini "aşağı kaydırma" kadar kolay hale getirin.
  5. Üst düzey "API" dokümanları ile alakalı "eğitici içerikler" arasında bağlantı oluşturmak için merkezi bir strateji sağlar.
  6. Her parametre için olası birçok seçeneği taramanın tek tek doküman dizelerini kontrol edememesine neden olduğu API-doc patlamasından kaçının.

Bu yaklaşımın mevcut dokümanlara göre diğer avantajları şunlardır:

  1. Dokümanların merkezileştirme nedeniyle eskime olasılığı daha düşüktür.
  2. Şu anda kodu okuyarak öğrenilmesi gereken, matplotlib'in "dolaylı standartlarının" ("sınırlar" ve "uzantılar" gibi) çoğunun standartlaştırılması.
  3. Bu süreç, API tutarlılığıyla ilgili sorunları GitHub sorun izleyicisi aracılığıyla daha kolay izlenebilecek şekilde vurgular ve API'mizi iyileştirme sürecine yardımcı olur.
  4. Ayrıştırılması gereken metin miktarındaki önemli düşüşler nedeniyle daha kısa doküman derleme süreleri.

Uygulama

Yukarıda açıklanan iyileştirmeler için, kendini bu işe adamış bir teknik yazarın paha biçilmez olacağı iki temel çalışma gerekecektir. İlki, örtülü tür başına bir adet merkezi "eğitici" sayfası oluşturmaktır. Bu, dokümanları kullanıcılar için değerli olan örtülü türlerin somut bir listesini belirlemek üzere çekirdek geliştirici ekibiyle birlikte çalışmayı gerektirir (genellikle, bunlar kitaplığımızın güçlü ve gizli özelliklerini içerir. Çünkü dokümanları şu anda yalnızca eğiticiler arasında titizlikle bulunan belgelerde bulunur). Daha sonra her örtülü tür için çeşitli ilgili eğiticileri, API belgelerini ve örnek sayfalarını, belirli bir türün referans verildiği herhangi bir yere bağlanabilecek tek bir yetkili belge kaynağı halinde sentezleyeceğim.

Belirli bir örtülü tür için merkezi belgeler tamamlandıktan sonra ikinci büyük çaba başlar: hem Python'un yerleşik help() yardımcı programını kullananlar hem de belgelerimize internette göz atan kullanıcılar için bu yeni belgeleri kullanma deneyimini mümkün olduğunca kolaylaştırmak amacıyla mevcut API belgelerini yeni belgelere yönlendiren bağlantılarla değiştirerek.

Bu proje geliştikçe, burada önerilen belgelerin tam biçimi değişebilir ancak Matplotlib çekirdek ekibiyle haftalık "geliştirme çağrıları" sırasında burada teklif edilen stratejinin, bu "dolaylı türleri" belgelemeye başlamak için en uygun, yararlı ve teknik açıdan uygun yaklaşım olduğu konusunda bir fikir birliğine varmamı sağladım (bu "dolaylı türlerin" belgelenmesine ilişkin notlar mevcuttur. Her örtülü tür için merkezi belge oluşturmanın ilk aşamalarında mevcut "eğitici içerikler" altyapısını kullanacağım. Böylece, yeni herkese açık sınıflar oluşturmak zorunda kalmadan (yine örnek olarak LineCollection belgelerini kullanarak) bu sayfalara aşağıdaki gibi kolaylıkla başvurabilirim:

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

İleride, çekirdek geliştirici ekibi yeni "türler" belgelerimizi gerçek Python sınıflarına dahil etmek için en iyi uzun vadeli strateji üzerinde anlaştıktan sonra bu referansların yazılışını kolayca değiştirebiliriz (örneğin, Matplotlib Geliştirme Teklifi 30 bölümünde önerdiğimiz şekilde).

Son olarak, bu Google Dokümanlar Sezonu sırasında belgelemeyi önerdiğim örtülü türlerin ön listesi şu şekildedir:

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

Bu belgenin yaşayan bir sürümünü Discourse'ta bulabilirsiniz.