Trang này chứa thông tin chi tiết về một dự án viết kỹ thuật được chấp nhận cho Phần Google Tài liệu.
Tóm tắt dự án
- Tổ chức nguồn mở:
- Nền tảng điện toán đám mây gốc (CNCF)
- Người viết nội dung kỹ thuật:
- đáng sợ
- Tên dự án:
- Cập nhật cách trang web Kubernetes phân phát tài liệu tham khảo API
- Thời lượng dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Hiện tại, Tài liệu tham khảo API của Kernetes là các tài liệu HTML có kích thước lớn được tạo từ thông số kỹ thuật của Swagger bởi các tập lệnh được lưu trữ bên ngoài kho lưu trữ trang web, sau đó được thêm vào kho lưu trữ của trang web này.
Bên cạnh đó, trang web tài liệu vềKubernetes được xây dựng bằng Hugo dựa trên các tài liệu được viết ở định dạng Markdown trong kho lưu trữ trang web, sử dụng giao diện Tài liệu Hugo.
Mục tiêu của dự án này là tích hợp quy trình tạo tài liệu tham chiếu API Kubernetes vào quy trình xây dựng trang web tài liệu.
Cụ thể, chúng ta sẽ tập trung vào swaggerui shortcode, trình bao bọc xung quanh swagger-ui, do giao diện Docsy Hugo cung cấp và trên các công cụ cụ thể, cho phép chèn các phần của thông số API vào quy trình tài liệu của Kubernetes.
Bạn sẽ cần sử dụng công cụ cụ thể vì swagger-ui có thể xuất ra thông số kỹ thuật hoàn chỉnh được mô tả trong tệp swagger, chứ không phải các phần trong tệp (xem 8). API Kubernetes quá lớn nên không thể hiển thị trong một phần (ví dụ về kết quả đầu ra). Chúng ta sẽ xem xét hai phương pháp:
cách tiếp cận đầu tiên là tạo một số tệp Swaggerui, mỗi tệp cho mỗi nhóm API Kubernetes (core/v1, ứng dụng/v1, v.v.) từ các nguồn có tại (10) và sử dụng các tệp này làm dữ liệu đầu vào của mã phân loại swaggerui tại những vị trí cụ thể trong trang web tài liệu của Kubernetes,
phương pháp thứ hai là tạo một công cụ để nhập tệp swagger hoàn chỉnh của API Kubernetes tại (11) rồi xuất ra một tệp swagger mới cho một điểm cuối cụ thể hoặc một số lượng điểm cuối giới hạn, cũng như các tài nguyên và định nghĩa có liên quan. Sau đó, sử dụng các tệp swagger làm dữ liệu đầu vào của mã ngắn swaggerui tại những vị trí cụ thể trong trang web tài liệu về Kubernetes.
Vì nguồn của thông số kỹ thuật (10 và 11) nằm ở các kho lưu trữ khác so với nguồn của tài liệu, nên chúng ta sẽ cần tìm cách tự động cập nhật chúng trong kho lưu trữ tài liệu khi chúng thay đổi.
Vì tài liệu về Kubernetes được cung cấp bằng nhiều ngôn ngữ nên chúng tôi sẽ đặc biệt chú ý đến khả năng xuất bản bản dịch để làm tài liệu tham khảo API Kubernetes.