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:
- Bulutta Yerel Bilişim Vakfı (CNCF)
- Teknik yazar:
- feloy
- Projenin adı:
- Kubernetes web sitesinin API referanslarını yayınlama ş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 özelliklerinden yararlanarak bu web sitesi deposuna eklenen büyük HTML dokümanlarıdır.
Diğer taraftan Kubernetes dokümanları web sitesi, web sitesi deposundaki Markdown formatında Dokümanlary Hugo teması kullanılarak yazılmış dokümanlardan Hugo ile derlenmiştir.
Bu projenin amacı, Kubernetes API referanslarının oluşturulmasını belge web sitesini oluşturan sürece entegre etmektir.
Daha ayrıntılı olarak açıklamak gerekirse, swaggerui kısa koduna odaklanacağız. Bu paket, Docsy Hugo teması tarafından sunulan ve swagger-ui'yi kapsayan sarmalayıcılar ve belirli araçlar hakkındadır. Böylece, Kubernetes belgelerinin akışına API spesifikasyonunun parçalarının eklenmesini sağlayacağız.
swagger-ui, promosyon dosyasında açıklanan tüm spesifikasyonların çıkışını üretebildiği ancak dosyanın bazı bölümlerinin çıkışını yapamadığı için belirli araçlar gerekir (bkz. 8). Kubernetes API, yalnızca bir bölümde gösterilemeyecek kadar büyük (bir çıkış örneği). İki yaklaşımı değerlendireceğiz:
İlk yaklaşım, her Kubernetes API grubu (çekirdek/v1, uygulamalar/v1, ...) için (10) bağlantısında bulunan kaynaklardan bir adet olmak üzere birkaç promosyon dosyası oluşturmak ve bu dosyaları Kubernetes belgeleri web sitesinin belirli yerlerinde promosyon kodu girişi olarak kullanmaktır.
İkinci yaklaşım, (11) bağlantısında bulunan Kubernetes API'nin tüm promosyon dosyasını girdi olarak kullanan ve belirli bir uç nokta ya da sınırlı sayıda uç nokta ve bunların ilişkili kaynakları ve tanımları için yeni bir promosyon dosyası oluşturan bir araç oluşturmaktır. Daha sonra, bu promosyon dosyalarını Kubernetes belgeleri web sitesinin belirli yerlerinde promosyon kodu (swaggerui kısa kodu) girişi olarak kullanabilirsiniz.
Spesifikasyon kaynakları (10 ve 11) belgelerin kaynakları dışındaki depolarda bulunduğundan, değiştikleri durumlarda bunları doküman havuzda otomatik olarak güncellemenin bir yolunu bulmamız gerekir.
Kubernetes belgeleri farklı dillerde mevcut olduğundan, Kubernetes API referansı için çeviri yayınlama olasılığına özellikle dikkat edeceğiz.