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:
- İzin verilen girişler için belgeleri tamamlama bağlantısı (
Line2D.set_linestyle
ve çizgi stili eğiticisinde bulunanların bir kombinasyonu). - 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:
- Her bir işlevin düz metinde açıkça görülebileceklerini tam olarak sunmak (sıfır tıklama gerekmez).
- 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.
- 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.
- 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.
- Üst düzey "API" dokümanları ile alakalı "eğiticiler" arasında bağlantı oluşturmak için merkezi bir strateji sağlama.
- 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ı:
- Dokümanların merkezileştirme nedeniyle eskime olasılığı daha düşüktür.
- Ş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ı.
- 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.
- 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:
capstyle
joinstyle
bounds
extents
linestyle
colors
/lists of colors
colornorm/colormap
tick formatters
Bu belgenin yaşayan bir sürümünü Discourse'ta bulabilirsiniz.