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