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:
- Cloud Native Computing Foundation (CNCF)
- Teknik yazar:
- dost
- Proje adı:
- Kubernetes web sitesinin API referanslarını sunma şeklini güncelleme
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
Şu anda Kubernetes API referansları, web sitesi deposunun dışında barındırılan komut dosyaları tarafından Swagger spesifikasyonlarından oluşturulan ve ardından bu web sitesi deposuna eklenen büyük HTML dokümanlarından oluşuyor.
Diğer taraftan, Kubernetes doküman web sitesi, web sitesi deposunda Markdown biçiminde yazılmış dokümanlar Hugo ile oluşturulur ve Docsy Hugo teması kullanılır.
Bu projenin amacı, Kubernetes API referanslarının oluşturulmasını doküman web sitesini oluşturan sürece entegre etmektir.
Özellikle, Docsy Hugo teması tarafından sağlanan swagger-ui sarmalayıcısı olan swaggerui kısa koduna ve API spesifikasyonunun bazı bölümlerinin Kubernetes dokümanları akışına eklenmesini sağlayan belirli araçlara odaklanacağız.
swagger-ui, swagger dosyasında açıklanan spesifikasyonun tamamını ancak bölümlerini değil (bkz. 8. adım) yayınlayabileceğinden belirli araçlara ihtiyaç duyulur. Kubernetes API, yalnızca bir bölümde gösterilemeyecek kadar büyüktür (çıktı örneği). İki yaklaşımı dikkate alacağız:
İlk yaklaşım, (10) adresindeki kaynaklardan her Kubernetes API grubu(core/v1, apps/v1, ...) için birer swagger dosyası oluşturmak ve bu dosyaları Kubernetes dokümantasyon web sitesinin belirli yerlerinde swaggerui sıralama kodlarının girişi olarak kullanmaktır.
ikinci yaklaşım ise (11)'de bulunan Kubernetes API'nin eksiksiz promosyon dosyasını giriş olarak alıp belirli bir veya sınırlı sayıda uç nokta, bununla ilişkili kaynaklar ve tanımlar için yeni bir promosyon dosyası üreten bir araç oluşturmaktır. Ardından, bu promosyon dosyalarını Kubernetes belgeleri web sitesinin belirli yerlerinde promosyon kodları girişi olarak kullanabilirsiniz.
Spesifikasyonların kaynakları (10 ve 11), dokümanların kaynaklarından farklı depolarda bulunduğundan, değiştiğinde doküman deposunda otomatik olarak güncellemelerini sağlayacak bir yöntem bulmamız gerekiyor.
Kubernetes dokümanları farklı dillerde mevcut olduğundan Kubernetes API referansı için çeviri yayınlama olasılığına özellikle dikkat edeceğiz.