หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- มูลนิธิการประมวลผลที่ดำเนินการบนระบบคลาวด์ (CNCF)
- ผู้เขียนด้านเทคนิค:
- ฟีลอย
- ชื่อโปรเจ็กต์:
- อัปเดตวิธีที่เว็บไซต์ Kubernetes แสดงข้อมูลอ้างอิง API
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ปัจจุบันการอ้างอิง Kubernetes API คือเอกสาร HTML ขนาดใหญ่ที่สร้างขึ้นจากข้อกำหนดของ Swagger โดยสคริปต์ที่โฮสต์นอกที่เก็บเว็บไซต์ แล้วเพิ่มลงในที่เก็บของเว็บไซต์นี้
ในอีกด้านหนึ่ง เว็บไซต์เอกสารประกอบ Kubernetes สร้างด้วย Hugo จากเอกสารประกอบที่เขียนในรูปแบบ Markdown ในที่เก็บเว็บไซต์ โดยใช้ธีม Docsy Hugo
เป้าหมายของโครงการนี้คือการผสานรวมการสร้างการอ้างอิง Kubernetes API เข้ากับกระบวนการที่สร้างเว็บไซต์เอกสารประกอบ
กล่าวโดยเจาะจงคือเราจะมุ่งเน้นที่ swaggerui shortcode, Wrapper ที่มี swagger-ui ซึ่งมาจากธีม Docsy Hugo และเครื่องมือที่เฉพาะเจาะจง ซึ่งทำให้สามารถแทรกบางส่วนของข้อกำหนด API ในขั้นตอนของเอกสารประกอบของ Kubernetes ได้
ต้องใช้เครื่องมือที่เฉพาะเจาะจงเนื่องจาก swagger-ui สามารถแสดงข้อมูลจำเพาะทั้งหมดที่อธิบายไว้ในไฟล์แบบสับเปลี่ยน แต่ไม่ใช่บางส่วนของไฟล์ (ดูข้อ 8) Kubernetes API มีขนาดใหญ่เกินไปที่จะแสดงในส่วนเดียวเท่านั้น (ตัวอย่างของเอาต์พุต) เราจะพิจารณา 2 แนวทางดังนี้
แนวทางแรกคือการสร้างไฟล์ S อย่างไรก็ตาม ไฟล์หนึ่งสำหรับแต่ละกลุ่ม Kubernetes API (หลัก/v1, แอป/v1, ...) จากแหล่งข้อมูลที่มีอยู่ใน (10) และใช้ไฟล์เหล่านี้เป็นอินพุตของ swคนหนึ่งรหัสจัดเรียงในที่หนึ่งๆ ในเว็บไซต์เอกสารประกอบของ Kubernetes
แนวทางที่ 2 คือการสร้างเครื่องมือที่จะรับอินพุตเป็นไฟล์ Sw {7/} ที่สมบูรณ์ของ Kubernetes API ซึ่งพบได้ที่ (11) และส่งออกไฟล์ Swaggerui ใหม่สำหรับปลายทางที่เจาะจงหรือปลายทางจำนวนจำกัด ตลอดจนทรัพยากรและคำนิยามที่เกี่ยวข้อง จากนั้นใช้ไฟล์ Sw {7/} เหล่านี้เป็นอินพุตของเอกสารย่อของ Kubernetes ที่ตำแหน่งที่เฉพาะเจาะจงของเว็บไซต์
เนื่องจากแหล่งที่มาของข้อกำหนดเฉพาะ (10 และ 11) อยู่ในที่เก็บอื่นซึ่งไม่ใช่ต้นฉบับของเอกสาร เราจึงต้องหาวิธีอัปเดตข้อกำหนดในที่เก็บเอกสารโดยอัตโนมัติเมื่อมีการเปลี่ยนแปลง
เนื่องจากเอกสารประกอบของ Kubernetes เป็นภาษาต่างๆ เราจึงให้ความสนใจเป็นพิเศษกับความเป็นไปได้ในการเผยแพร่คำแปลสำหรับการอ้างอิง Kubernetes API