Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- Cloud Native Computing Foundation (CNCF)
- Penulis teknis:
- feloy
- Nama project:
- Memperbarui cara situs Kubernetes menayangkan referensi API
- Durasi project:
- Durasi standar (3 bulan)
Project description
Saat ini, referensi Kubernetes API adalah dokumen HTML besar yang dihasilkan dari spesifikasi Swagger oleh skrip yang dihosting di luar repositori situs, lalu ditambahkan ke repositori situs ini.
Di sisi lain, situs dokumentasi Kubernetes dibuat dengan Hugo dari dokumentasi yang ditulis dalam format Markdown di repositori situs, menggunakan tema Docsy Hugo.
Tujuan project ini adalah untuk mengintegrasikan pembuatan referensi Kubernetes API ke dalam proses yang mem-build situs dokumentasi.
Secara khusus, kita akan berfokus pada shortcode swaggerui, wrapper di sekitar swagger-ui, yang disediakan oleh tema Docsy Hugo dan pada alat tertentu, yang memungkinkan penyisipan bagian spesifikasi API dalam alur dokumentasi Kubernetes.
Alat khusus akan diperlukan karena swagger-ui dapat menghasilkan spesifikasi lengkap yang dijelaskan dalam file swagger, tetapi tidak menghasilkan bagian-bagiannya (lihat 8). Kubernetes API terlalu besar untuk ditampilkan di satu bagian saja (contoh output). Kita akan mempertimbangkan dua pendekatan:
pendekatan pertama adalah membuat beberapa file swagger, satu untuk setiap grup Kubernetes API (core/v1, apps/v1, ...) dari sumber yang tersedia di (10) dan menggunakan file ini sebagai input kode pengurutan swaggerui di tempat tertentu di situs dokumentasi Kubernetes,
Pendekatan kedua adalah membuat alat yang mendapatkan file swagger lengkap dari Kubernetes API sebagai input yang ditemukan di (11) dan menghasilkan file swagger baru untuk endpoint tertentu atau sejumlah endpoint terbatas, serta resource dan definisi terkait, lalu menggunakan file swagger ini sebagai input shortcode swaggerui di tempat tertentu di situs dokumentasi Kubernetes.
Karena sumber spesifikasi (10 dan 11) berada di repositori lain selain sumber dokumentasi, kita harus menemukan cara untuk memperbaruinya secara otomatis di repositori dokumentasi saat spesifikasi berubah.
Karena dokumentasi Kubernetes tersedia dalam berbagai bahasa, kami akan memberikan perhatian khusus pada kemungkinan publikasi terjemahan untuk referensi Kubernetes API.