本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- Cloud Native Computing Foundation (CNCF)
- 技术文档工程师：
- feloy
- 项目名称：
- 更新 Kubernetes 网站提供 API 引用的方式
- 项目时长：
- 标准时长（3 个月）
Project description
目前，Kubernetes API 参考内容是由网站代码库之外托管的脚本根据 Swagger 规范生成并添加到此网站代码库中的大型 HTML 文档。
另一方面，Kubernetes 文档网站是使用 Docsy Hugo 主题，基于网站代码库中以 Markdown 格式编写的文档使用 Hugo 构建而成。
此项目的目标是将生成 Kubernetes API 引用整合到构建文档网站的过程中。
具体而言，我们将重点介绍 swaggerui 短代码（即由 Docsy Hugo 主题提供的 swagger-ui 的封装容器），以及具体的工具，以便将 API 规范的某些部分插入到 Kubernetes 文档流程中。
您将需要特定的工具，因为 swagger-ui 能够输出 swagger 文件中所述的完整规范，而不是其中的一部分（参见 8）。Kubernetes API 太大，无法仅在一个部分显示（输出示例）。我们将考虑两种方法：
第一种方法是从 (10) 处提供的来源为每个 Kubernetes API 组（核心/v1、应用/v1...）创建多个 Swagger 文件，然后将这些文件用作 Kubernetes 文档网站中特定位置的 swaggerui 排序代码的输入。
第二种方法是创建一个工具，将 (11) 处的 Kubernetes API 的完整 Swagger 文件作为输入，并针对特定端点或有限数量的端点输出新的 Swagger 文件及其关联的资源和定义，然后将这些 swagger 文件用作 Kubernetes 文档网站中特定位置的 swaggerui 短代码的输入。
由于规范的源代码（10 和 11）并非文档来源，而是位于其他代码库中，因此我们需要想办法在它们发生更改时自动更新文档库。
由于 Kubernetes 文档有不同语言版本，因此我们会特别注意为 Kubernetes API 参考发布翻译的可能性。