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