Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.
Tóm tắt dự án
- Tổ chức nguồn mở:
- Cloud Native Computing Foundation (CNCF)
- Người viết nội dung kỹ thuật:
- feloy
- 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 hạn tiêu chuẩn (3 tháng)
Mô tả dự án
Hiện tại, tài liệu tham khảo API Kubernetes là các tài liệu HTML lớn được tạo từ thông số kỹ thuật Swagger bằng 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ữ trang web này.
Mặt khác, trang web tài liệu về Kubernetes được tạo bằng Hugo từ tài liệu được viết ở định dạng Markdown trong kho lưu trữ trang web, sử dụng giao diện Hugo Docsy.
Mục tiêu của dự án này là tích hợp việc tạo tệp tham chiếu API Kubernetes vào quy trình tạo trang web tài liệu.
Cụ thể, chúng ta sẽ tập trung vào đoạn mã ngắn swaggerui, trình bao bọc xung quanh swagger-ui, do giao diện Docsy Hugo cung cấp và công cụ cụ thể, cho phép chèn các phần của thông số kỹ thuật API trong luồng tài liệu về Kubernetes.
Bạn sẽ cần có công cụ cụ thể vì swagger-ui có thể xuất ra thông số kỹ thuật đầy đủ được mô tả trong tệp swagger, nhưng không phải một phần của thông số kỹ thuật đó (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ả). Chúng ta sẽ xem xét hai phương pháp:
phương pháp đầu tiên là tạo một số tệp swagger, mỗi tệp cho một nhóm API Kubernetes (core/v1, apps/v1, ...) từ các nguồn có sẵn tại (10) và sử dụng các tệp này làm dữ liệu đầu vào của mã sắp xếp swaggerui tại các vị trí cụ thể trong trang web tài liệu Kubernetes,
phương pháp thứ hai là tạo một công cụ nhận tệp swagger đầy đủ của API Kubernetes tại (11) làm dữ liệu đầu vào và xuất một tệp swagger mới cho một điểm cuối cụ thể hoặc một số điểm cuối có giới hạn, cũng như các tài nguyên và định nghĩa liên quan, sau đó sử dụng các tệp swagger này làm dữ liệu đầu vào của mã ngắn swaggerui tại các vị trí cụ thể trong trang web tài liệu Kubernetes.
Vì nguồn của thông số kỹ thuật (10 và 11) nằm trong các kho lưu trữ khác ngoà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 hiện có 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 cho tài liệu tham khảo về API của Kubernetes.