Matplotlib projesi

Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.

Proje özeti

Açık kaynak kuruluşu:
Matplotlib
Teknik yazar:
brunobeltran
Proje adı:
"Implisit" türlerin belgelerini standartlaştırarak özellik bulunabilirliğini artırma
Proje uzunluğu:
Uzun süreli (5 ay)

Proje açıklaması

Motivasyon

Geçmişte matplotlib'in API'si, dize-enum olarak "örtülü türlere" büyük ölçüde güveniyordu. Bu parametre dizeleri, matlab'ın API'sini taklit etmenin yanı sıra kullanıcının, temel çizim seçeneklerini iletmek için gerçek bir enum değerini açıkça içe aktarmak veya ayrıntılı bir şekilde önek eklemek zorunda kalmadan semantik açıdan zengin değerleri matplotlib işlevlerine bağımsız değişken olarak iletmesine olanak tanır (ör. plt.plot(x, y, linestyle='solid'), plt.plot(x, y, linestyle=mpl.LineStyle.solid) gibi bir değere kıyasla yazması daha kolay ve daha az gereksizdir).

Bu liste olarak dize olan gizli türlerin çoğu, o zamandan beri daha gelişmiş özelliklere dönüştü. Örneğin, linestyle artık bir dize veya 2 dizilim olabilir. MarkerStyle ise artık bir dize veya matplotlib.path.Path olabilir. Bu durum birçok örtük tür için geçerli olsa da MarkerStyle, uygun bir Python sınıfına yükseltilmiş durumda olan tek türdür (bildiğim kadarıyla).

Bu gizli türler kendi başına sınıf olmadığından, Matplotlib'in geçmişte Python sınıfları tarafından sağlanan standart araç zincirlerini (ör. docstring'ler ve __init__ adresinde doğrulama kalıbı) kullanmak yerine bu gizli türlerin dokümantasyonunu ve doğrulamasını merkezileştirmek için kendi çözümlerini sunması gerekiyordu (ör. docstring.interpd.update docstring interpolasyon kalıbı ve cbook._check_in_list doğrulayıcı kalıbı).

Bu çözümler bizim için iyi sonuç verdiyse de her bir gizli türün belgeleneceği net bir konum olmaması, dokümanların genellikle bulunmasının zor olduğu anlamına geliyor. İzin verilen değerlerin bulunduğu büyük tablolar dokümanlar boyunca tekrarlanıyor ve genellikle gizli bir türün kapsamının net bir açıklaması dokümanlarda eksik. plt.plot belgelerini ele alalım. Örneğin, "Notlar" bölümünde, matlab benzeri biçim dizesi stil yönteminin açıklamasında linestyle, color ve markers seçenekleri yer almaktadır. Bu üç değeri iletmenin, burada bahsedilenlerden çok daha fazla yolu vardır. Ancak birçok kullanıcı, ilgili eğitimlerden birine rastlayana kadar bu seçenekler için hangi değerlerin kullanılabileceği hakkında bilgi edinmek için yalnızca bu kaynağı kullanır. Okuyucuya olay örgüsünü kontrol etmek için hangi seçeneklere sahip olduğunu göstermek amacıyla Line2D özellikleri tablosu eklenmiştir. Ancak linestyle girişi, olası girişlerin açıklandığı Line2D.set_linestyle (iki tıklama gerekir) sayfasına bağlantı vererek iyi bir iş çıkarırken color ve markers girişleri bunu yapmaz. color, Line2D.set_color'e yalnızca bağlantı verir. Bu da ne tür girişlere izin verildiği konusunda hiçbir fikir vermez.

Bu sorunun, soruna neden olan docstring'lerin düzenlenmesiyle çözülebileceği söylenebilir ancak maalesef sorun bundan çok daha sistemsel. Belgeleri bulabilecekleri merkezi bir yer olmadığında bu, bu örtülü türlerin her birinin kullanıldığı her yerde gittikçe artan sayıda ayrıntılı belge kopyasının sürekli olarak tekrarlanmasına yol açar. Bu durum, yeni başlayan kullanıcıların ihtiyaç duydukları parametreyi kolayca bulmasını zorlaştırır. Ancak kullanıcıları, dokümanlarımız arasında wiki tarzında gezinerek veya StackOverflow örneklerinden parça parça inceleyerek her bir örtülü türe dair zihinsel modellerini yavaş yavaş bir araya getirmeye zorlayan mevcut sistem de sürdürülebilir değildir.

Bitiş Hedefi

İdeal olarak, bir örtülü türden bahsedildiğinde, türün alabileceği tüm olası değerleri en basit ve yaygından en gelişmiş veya gizemliye göre sıralanmış şekilde açıklayan tek bir sayfaya bağlantı verilmelidir. Belirli bir parametrenin tüm olası giriş türlerini parça parça listelemek için üst düzey API dokümanlarında değerli görsel alanı kullanmak yerine, aynı alanı kullanarak parametrenin kontrol etmeyi amaçladığı nokta çizme soyutlaması hakkında basit bir açıklama sunabiliriz.

linestyle örneğini tekrar kullanırsak LineCollection dokümanlarındaki istediğimiz şey şudur:

  1. İzin verilen girişler için dokümanları tamamlama bağlantısı (Line2D.set_linestyle ve çizgi stili eğitimindeki dokümanların bir kombinasyonu).
  2. Parametrenin amacının ne olduğuna dair basit bir açıklama. Matplotlib'i kullananlar için bu durum parametrenin adından açıkça anlaşılsa da yeni kullanıcılar için bu durum geçerli değildir.

Bunun gerçek LineCollection dokümanlarındaki görünümü şu şekildedir: 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 tür referansı, Matplotlib'in çizgi stillerini nasıl ele aldığına dair tek, yetkili ve eksiksiz bir doküman grubuna yönlendirmek için Sphinx tarafından çözülür.

Avantajları

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

  1. Her işlevin yapabileceklerinin tamamını açık metinde net bir şekilde gösterme (sıfır tıklama gerektirmez).
  2. Varsayılan seçeneği görünür hale getirmek (sıfır tıklama ile). Varsayılan seçeneği görmek, geri gelen kullanıcıların hafızasını canlandırmak için genellikle yeterlidir.
  3. Tarama sırasında kolayca erişilebilen (tek tıklamayla) bir parametre için "en yaygın" ve "en kolay" seçeneklerin tam açıklamasını yapın.
  4. Daha güçlü özellikleri ve giriş yöntemlerini keşfetme sürecini, daha gelişmiş seçenekleri görmek için "aşağı kaydır" kadar kolay hale getirin (yine de tek tıklamayla).
  5. Üst düzey ""API"" dokümanlarını ilgili ""eğitimler""e bağlamak için merkezi bir strateji sağlayın.
  6. Her parametreye yönelik olası birçok seçenek üzerinden tarama yapmanın tek tek doküman dizelerini kontrol altına almasına neden olduğu API-doküman patlamasından kaçının.

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

  1. Merkezileştirme sayesinde dokümanların güncelliğini kaybetme olasılığı daha düşüktür.
  2. Şu anda kodu okuyarak öğrenilmesi gereken matplotlib'in "örtük standartlarının" (ör. "bounds" ve "extents" arasındaki fark) çoğunun standartlaştırılması.
  3. Bu süreç, API tutarlılığıyla ilgili sorunları GitHub sorun izleyici üzerinden daha kolay takip edilebilecek şekilde vurgular ve API'mizi iyileştirme sürecine yardımcı olur.
  4. Ayrıştırılması gereken metin miktarındaki önemli düşüşler sayesinde, daha hızlı belge derleme süreleri.

Uygulama

Yukarıda açıklanan iyileştirmeler için iki büyük çalışma yapılması gerekir. Bu çalışmalarda özel bir teknik yazarın yardımı çok değerli olacaktır. Birincisi, her bir gizli tür için merkezi bir "eğitim" sayfası oluşturmaktır. Bu, dokümanları kullanıcılar için değerli olacak (genellikle, dokümanları şu anda yalnızca bulunması zor eğitimlerde bulunan kitaplığımızın güçlü ve gizli özelliklerini içerdikleri için) soyut türlerin somut bir listesini belirlemek üzere çekirdek geliştirici ekibiyle birlikte çalışmayı gerektirir. Ardından, her bir örtülü tür için çeşitli ilgili eğitici içerikleri, API dokümanlarını ve örnek sayfaları, söz konusu türe atıfta bulunulan her yere bağlanabilecek tek bir yetkili doküman kaynağında birleştireceğim.

Belirli bir gizli türe ait merkezi dokümanlar tamamlandıktan sonra ikinci büyük çalışma başlar: Hem Python'un yerleşik help() yardımcı programını kullananlar hem de dokümanlarımıza internetten göz atanlar için bu yeni dokümanları kullanma deneyimini mümkün olduğunca kolaylaştırmak amacıyla mevcut API dokümanlarını yeni dokümanların bağlantılarıyla değiştirme.

Burada önerilen dokümantasyonun tam biçimi, proje geliştikçe değişebilir. Burada önerilen stratejinin, bu "örtülü türleri" belgelemeye başlamak için en uygun, yararlı ve teknik olarak uygulanabilir yaklaşım olduğu konusunda fikir birliğine varmak üzere haftalık "geliştirici toplantıları" sırasında Matplotlib çekirdek ekibiyle birlikte çalıştım (bu toplantılarla ilgili notlara hackmd'den ulaşabilirsiniz). Her bir gizli tür için merkezi dokümanlar oluşturmanın ilk aşamalarında mevcut "eğitimler" altyapısını kullanacağım. Bu sayede, yeni herkese açık sınıflar oluşturmak zorunda kalmadan bu sayfalara aşağıdaki gibi kolayca referans verebilirim (yine örnek olarak LineCollection dokümanlarını kullanacağı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`.
""""""

Gelecekte, çekirdek geliştirici ekibi yeni "tür" dokümanlarımızı gerçek Python sınıflarına dahil etmek için en iyi uzun vadeli stratejiyi belirledikten sonra bu referansların yazılışını kolayca değiştirebiliriz. Örneğin, Matplotlib Geliştirme Önerisi 30'da önerdiğim gibi.

Son olarak, bu Google Dokümanlar Sezonu sırasında belgelenmesini önerdiğim gizli türlerin ön listesi şunlardır:

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

Bu dokümanın güncel sürümünü Discourse'da bulabilirsiniz.