이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- Cloud Native Computing Foundation (CNCF)
- 테크니컬 라이터:
- 펠로이
- 프로젝트 이름:
- Kubernetes 웹사이트에서 API 참조를 제공하는 방법 업데이트
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
현재 Kubernetes API 참조는 웹사이트 저장소 외부에서 호스팅된 스크립트에 의해 Swagger 사양에서 생성되어 이 웹사이트 저장소에 추가된 대형 HTML 문서입니다.
또 다른 측면에서는 Kubernetes 문서 웹사이트가 Docsy Hugo 테마를 사용하여 웹사이트 저장소에 마크다운 형식으로 작성된 문서를 휴고와 함께 구축한 것입니다.
이 프로젝트의 목표는 Kubernetes API 참조 생성을 문서 웹사이트를 빌드하는 프로세스에 통합하는 것입니다.
특히 Docsy Hugo 테마에서 제공하는 swagger-ui 주변의 래퍼인 swaggerui 단축 코드와 특정 도구에 중점을 두고 Kubernetes 문서의 흐름에 API 사양의 일부를 삽입할 수 있도록 합니다.
swagger-ui는 swagger 파일에 설명된 전체 사양을 출력할 수 있지만 그 일부는 출력할 수 없으므로 특정 도구가 필요합니다(8 참고). Kubernetes API가 너무 커서 한 부분으로만 표시할 수 없습니다(출력 예시). 여기서는 두 가지 접근 방식을 고려할 것입니다.
첫 번째 접근 방식은 (10)에 있는 소스에서 Kubernetes API 그룹(core/v1, apps/v1, ...)마다 하나씩 여러 개의 스웨거 파일을 만들고 이러한 파일을 Kubernetes 문서 웹사이트의 특정 위치에서 swaggerui 정렬 코드의 입력으로 사용하는 것입니다.
두 번째 접근 방식은 (11)에 있는 Kubernetes API의 완전한 스웨거 파일을 입력으로 가져와서 특정 엔드포인트 또는 제한된 수의 엔드포인트에 대한 새 swagger 파일, 관련 리소스 및 정의를 출력하는 도구를 만든 다음, 이러한 swagger 파일을 Kubernetes 문서 웹사이트의 특정 위치에서 swaggerui 단축 코드의 입력으로 사용하는 것입니다.
사양의 소스 (10 및 11)는 문서의 소스가 아닌 다른 저장소에 있으므로, 문서가 변경될 때 문서 저장소에서 이를 자동으로 업데이트할 방법을 찾아야 합니다.
Kubernetes 문서는 여러 언어로 제공되므로 Kubernetes API 참조용 번역을 게시할 수 있다는 점에 특히 주의를 기울일 것입니다.