בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון בקוד פתוח:
- Cloud Native Computing Foundation (CNCF)
- כותבים טכניים:
- feloy
- שם הפרויקט:
- לעדכן את האופן שבו אתר Kubernetes שולח הפניות ל-API
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
נכון לעכשיו, מקורות המידע של Kubernetes API הם מסמכי HTML גדולים שנוצרו ממפרטי Swagger באמצעות סקריפטים שמתארחים מחוץ למאגר האתר, ולאחר מכן נוספו למאגר האתר הזה.
לעומת זאת, אתר המסמכים של Kubernetes נוצר באמצעות Hugo ממסמכים שנכתבו בפורמט Markdown במאגר האתר, באמצעות העיצוב Docsy של Hugo.
מטרת הפרויקט היא לשלב את היצירה של הפניות ל-Kubernetes API בתהליך היצירה של אתר התיעוד.
נתמקד ספציפית בקוד המקוצר של swaggerui, wrapper במסגרת swagger-ui, שמסופק על ידי העיצוב של Docsy Hugo וכלים ספציפיים, ומאפשר הוספה של חלקים ממפרט ה-API בתהליך התיעוד של Kubernetes.
יהיה צורך בכלים ספציפיים, כי swagger-ui יכול להפיק את המפרט המלא שמתואר בקובץ swagger, אבל לא חלקים ממנו (ראו 8). ממשק ה-API של Kubernetes גדול מדי כדי להציג אותו בחלק אחד בלבד (דוגמה לפלט). נבחן שתי גישות:
הגישה הראשונה היא ליצור כמה קובצי swagger, אחד לכל קבוצת API של Kubernetes (core/v1, apps/v1 וכו') ממקורות שזמינים בכתובת (10), ולהשתמש בקבצים האלה כקלט של קודי מיון של swaggerui במקומות ספציפיים באתר של מסמכי התיעוד של Kubernetes.
הגישה השנייה היא ליצור כלי שמקבל כקלט את קובץ ה-Swagger המלא של Kubernetes API שנמצא ב-(11), ומפיק קובץ Swagger חדש לנקודת קצה ספציפית או למספר מוגבל של נקודות קצה, יחד עם המשאבים וההגדרות המשויכים, ולאחר מכן להשתמש בקובצי ה-Swagger האלה כקלט של קודי קיצור של swaggerui במקומות ספציפיים באתר של מסמכי התיעוד של Kubernetes.
מקורות המפרטים (10 ו-11) נמצאים במאגרים אחרים מאשר מקורות המסמכים, לכן נצטרך למצוא דרך לעדכן אותם באופן אוטומטי במאגר המסמכים כשיהיו שינויים.
מאחר שהמסמכים של Kubernetes זמינים בשפות שונות, נקדיש תשומת לב מיוחדת לפרסום תרגומים של הספרייה של Kubernetes API.