این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه ی پروژه
- سازمان منبع باز:
- بنیاد محاسبات بومی ابری (CNCF)
- نویسنده فنی:
- جنایتکار
- نام پروژه:
- نحوه خدمت رسانی وب سایت Kubernetes به مراجع API را به روز کنید
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
در حال حاضر، مراجع API Kubernetes اسناد HTML بزرگی هستند که از مشخصات Swagger توسط اسکریپت‌هایی که خارج از مخزن وب‌سایت میزبانی می‌شوند، تولید می‌شوند و سپس به این مخزن وب‌سایت اضافه می‌شوند.
از طرف دیگر، وب‌سایت اسناد Kubernetes با Hugo از اسنادی که با فرمت Markdown در مخزن وب‌سایت نوشته شده است، با استفاده از موضوع Docsy Hugo ساخته شده است.
هدف این پروژه ادغام تولید مراجع API Kubernetes در فرآیند ساخت وب سایت مستندسازی است.
به طور خاص، ما بر روی کد کوتاه swaggerui تمرکز خواهیم کرد، بسته بندی در اطراف swagger-ui ، ارائه شده توسط موضوع Docsy Hugo و بر روی ابزار خاص، که امکان درج بخشی از مشخصات API را در جریان اسناد Kubernetes فراهم می کند.
ابزار خاصی مورد نیاز خواهد بود زیرا swagger-ui قادر است مشخصات کامل توضیح داده شده در یک فایل swagger را خروجی دهد، اما نه بخش هایی از آن (نگاه کنید به 8) . Kubernetes API آنقدر بزرگ است که فقط در یک قسمت نمایش داده شود (نمونه ای از خروجی) . ما دو رویکرد را در نظر خواهیم گرفت:
روش اول ایجاد چندین فایل swagger، یکی برای هر گروه Kubernetes API (core/v1، apps/v1، ...) از منابع موجود در (10) و استفاده از این فایل ها به عنوان ورودی کدهای swaggerui در مکان های خاص در Kubernetes است. وب سایت اسناد،
روش دوم ایجاد ابزاری است که فایل swagger کامل از Kubernetes API موجود در (11) را به عنوان ورودی دریافت می کند و یک فایل Swagger جدید را برای یک نقطه پایانی خاص یا تعداد محدودی از نقاط پایانی و منابع و تعاریف مرتبط با آن خروجی می گیرد، سپس از آن استفاده می کند. این فایل های swagger به عنوان ورودی کدهای کوتاه swaggerui در مکان های خاص در وب سایت اسناد Kubernetes.
از آنجایی که منابع مشخصات (10 و 11) در مخازن دیگری غیر از منابع مستندات قرار دارند، ما باید راهی پیدا کنیم که به طور خودکار آنها را در مخزن اسناد تغییر دهیم.
از آنجایی که اسناد Kubernetes به زبان های مختلف موجود است، ما به امکان انتشار ترجمه برای مرجع Kubernetes API توجه ویژه ای خواهیم داشت.