Matplotlib projesi

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

Proje özeti

Açık kaynak kuruluşu:
Matplotlib
Teknik yazar:
brunobeltra
Projenin adı:
"Kapalı" türlerle ilgili 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, büyük ölçüde enum olarak dize (ör. "dolaylı türler") kullanıyordu. Bu parametre dizeleri, matlab API'sini taklit etmenin yanı sıra kullanıcının, temel nokta seçeneklerini geçirmek için gerçek bir enum değerini açıkça içe aktarmak veya ayrıntılı olarak öne çıkarmak zorunda kalmadan (ör. plt.plot(x, y, linestyle='solid'), yazmak daha kolaydır ve plt.plot(x, y, linestyle=mpl.LineStyle.solid) gibi bir komuttan daha az gereksizdir) matplotlib işlevlerine bağımsız değişken olarak semantik olarak zengin değerler iletmesini sağlar.

Bu örtülü dize türlerinin çoğu, o zamandan beri daha gelişmiş özellikler geliştirmiştir. Örneğin, linestyle artık bir dize veya 2 unsurlu dizi olabilir. MarkerStyle ise artık dize veya matplotlib.path.Path olabilir. Bu, birçok örtülü tür için geçerli olsa da (bilgilerime göre), uygun bir Python sınıfına yükseltilmiş durumda olan tek MarkerStyle.

Bu örtülü türler kendi başlarına birer sınıf olmadığından, Matplotlib geçmişte belgeleri ve bu örtülü türlerin doğrulanması için eskiden kendi çözümlerini uygulamak zorunda kaldı (ör. sırasıyla docstring.interpd.update docstring interpolasyon modeli ve cbook._check_in_list doğrulayıcı modeli), Python sınıfları tarafından sağlanan standart araç zincirlerini (ör. docat-trestrings ve docat-restrings) doğrulamak yerine.__init__

Bu çözümler işe yaradı Ö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çeneklerinden bahsediliyor. Bu üç değeri aktarmanın, ipuçlarında belirtilenden çok daha fazla yolu vardır ancak birçok kullanıcı için ilgili eğiticilerden biriyle karşılaşana kadar bu seçenekler için hangi değerlerin mümkün olduğunu anlamaları için tek kaynak budur. Okuyucuya, şemasını kontrol etmek için hangi seçeneklere sahip olduğunu göstermek amacıyla Line2D özellikleri tablosu dahil edilir. Bununla birlikte, linestyle girişi, olası girişlerin açıklandığı yerde Line2D.set_linestyle ile bağlantı oluşturma konusunda iyi bir iş yapsa da (iki tıklama gerekli) color ve markers girişleri bunu yapmaz. color sadece Line2D.set_color ile bağlantı oluşturur. Bu da ne tür girişlere izin verildiği konusunda herhangi bir sezgi sağlayamaz.

Bunun, sorunlara neden olan tek tek doküman dizelerini düzelterek düzeltilebilecek bir durum olduğu iddia edilebilir, ancak sorun maalesef bundan çok daha sistematiktir. Belgeleri bulabilecekleri merkezi bir yer olmadığında, bu örtülü türlerin her birinin kullanıldığı her yerde, gittikçe artan bir şekilde ayrıntılı belgelerin tekrar eden kopyalarının bulunması yeterli olacaktır. Bu da yeni başlayan kullanıcıların ihtiyaç duydukları parametreyi kolayca bulmalarını zorlaştırır. Ancak, dokümanlarımızda wiki-dalma stili geçişi veya StackOverflow örneklerinden parça parça geçiş yoluyla her bir örtülü türden zihinsel modellerini yavaş yavaş bir araya getirmeye zorlayan mevcut sistem de sürdürülebilir değil.

Hedefi Sonlandır

İdeal olarak, örtülü bir türden bahsedildiğinde, ilgili türün alabileceği tüm olası değerleri açıklayan tek bir sayfaya bağlantı verilmelidir. Söz konusu değerler en basit ve yaygın olandan en ileri veya gizli olana doğru sıralanır. Belirli bir parametreye göre olası tüm giriş türlerini parça parça numaralandırmak için üst düzey API belgelerinde değerli görsel alan kullanmak yerine, aynı alanı, parametrenin kontrol etmek istediği soyutlamayla ilgili sade bir açıklama sunmak için kullanabiliriz.

linestyle örneğini tekrar kullanırsak LineCollection dokümanlarında şunu 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 tamamlamayı amaçladığını açıklayan sade bir açıklamadır. 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.

Bu, gerçek LineCollection dokümanlarında görülen 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. """""" şeklindedir. Burada LineStyle türü referansı, Matplotlib'in çizgi stillerini nasıl işlediğini gösteren tek, güvenilir ve eksiksiz bir belge grubunu işaret etmek üzere Sfenks tarafından çözülür.

Avantajları

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

  1. Her bir işlevin düz metinde açıkça görülebileceklerini tam olarak sunmak (sıfır tıklama gerekmez).
  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ı canlandırmak için yeterli olur.
  3. Göz atarken bir parametreye ilişkin ""en yaygın"" ve ""en kolay"" seçeneklerinin eksiksiz bir açıklamasını (tek tıklamayla) kolayca yapın.
  4. Daha gelişmiş seçenekleri (yine tek tıklamayla) görmek için daha güçlü özellikleri ve giriş yöntemlerini keşfetme sürecini "aşağı kaydırma" kadar kolay hale getirin.
  5. Üst düzey "API" dokümanları ile alakalı "eğiticiler" arasında bağlantı oluşturmak için merkezi bir strateji sağlama.
  6. Her parametre için olası birçok seçeneği taramanın bağımsız doküman dizelerini kontrolsüz hale getirdiği API-belgeleri patlamaktan kaçının.

Bu yaklaşımın mevcut dokümanlara kıyasla diğer avantajları:

  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 (ör. "sınırlar" ve "uzantılar" arasındaki) birçoğunun standartlaştırılması.
  3. Bu süreç, API tutarlılığıyla ilgili sorunları GitHub sorun izleyicisi aracılığıyla daha kolay takip edilebilecek şekilde vurgular ve API'mizi iyileştirme sürecine yardımcı olur.
  4. Ayrıştırılması gereken metin miktarında önemli düşüşler sağladığından daha kısa doküman derleme süreleri.

Uygulama

Yukarıda açıklanan iyileştirmeler için, özel olarak atanmış bir teknik yazarın paha biçilmez olacağı iki temel çalışma gerekecektir. İlki, örtülü tür başına tek bir merkezi "eğitim" sayfası oluşturmaktır. Bu, kullanıcılar açısından değerli olabilecek örtülü türlerin somut bir listesini belirlemek için çekirdek geliştirici ekibiyle birlikte çalışmayı gerektirecektir (genellikle bu türler kitaplığımızın güçlü ve gizli özelliklerini içerir. Bu özellikler, şu anda belgeleri yalnızca eğiticilerle titizlikle denk gelen videolarda bulunur). Ardından her örtülü tür için çeşitli ilgili eğiticileri, API belgelerini ve örnek sayfaları, belirli bir türe referansta bulunulan herhangi bir yere bağlanabilecek tek bir yetkili belge kaynağında 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 belgelerinin yeni belgelere yönelik bağlantılarla değiştirilmesi.

Bu proje geliştikçe burada önerilen belgelerin Her örtülü türe ait merkezi belgeleri oluşturmanın ilk aşamalarında mevcut "eğitici içerikler" altyapısını kullanacağım. Böylece, yeni genel sınıflar oluşturmak zorunda kalmadan (yine LineCollection örneklerini örnek olarak kullanarak) bu sayfalara aşağıdaki gibi kolayca başvuruda bulunacağım:

""""""
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 "types" belgelerimizi gerçek Python sınıflarına dahil etmek için en iyi uzun vadeli strateji üzerinde anlaştıktan sonra (örneğin, Matplotlib Geliştirme Önerisi 30'da önerdiğimiz şekilde), bu referansların yazım şeklini kolayca değiştirebiliriz.

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.