Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.
Ringkasan proyek
- Organisasi open source:
- Cloud Native Computing Foundation (CNCF)
- Penulis teknis:
- penjahat
- Nama proyek:
- Memperbarui cara situs Kubernetes menayangkan referensi API
- Durasi proyek:
- 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, kemudian 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 membangun situs dokumentasi.
Secara khusus, kita akan berfokus pada kode singkat swaggerui, wrapper seputar swagger-ui, yang disediakan oleh tema Docs Hugo dan alat khusus, yang memungkinkan penyisipan bagian spesifikasi API dalam alur dokumentasi Kubernetes.
Alat tertentu akan diperlukan karena swagger-ui mampu menghasilkan spesifikasi lengkap yang dijelaskan dalam file swagger, tetapi bukan sebagian dari spesifikasi (lihat 8). Kubernetes API terlalu besar untuk ditampilkan di satu bagian saja (contoh output). Kami 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 sortcode swaggerui di tempat tertentu dalam situs dokumentasi Kubernetes,
pendekatan kedua adalah membuat alat yang mendapatkan sebagai input file swagger lengkap Kubernetes API yang ditemukan di (11) dan menghasilkan file swagger baru untuk endpoint tertentu atau sejumlah endpoint yang terbatas, serta resource dan definisi terkaitnya, lalu menggunakan file swagger ini sebagai input kode pendek swaggerui di tempat tertentu di situs dokumentasi Kubernetes.
Karena sumber spesifikasi (10 dan 11) berada di repositori lain selain sumber dokumentasi, kami perlu menemukan cara untuk memperbaruinya secara otomatis di repositori dokumentasi saat sumber tersebut berubah.
Karena dokumentasi Kubernetes tersedia dalam berbagai bahasa, kami akan memberikan perhatian khusus pada kemungkinan memublikasikan terjemahan untuk referensi Kubernetes API.