本文已超过一年。较旧的文章可能包含过时的内容。请检查页面中的信息自发布以来是否已失效。

GSoD 2020：改进 API 参考文档体验

作者：Philippe Martin |

编者注：在我加入 Kubernetes 文档团队三年半以来，改进 API 参考文档一直是我的目标。Philippe 出色地完成了这项工作。更重要的是，Philippe 在这个项目中体现了 Kubernetes 社区最优秀的特质：通过协作追求卓越，以及一个让社区本身变得更好的过程。感谢 Google Season of Docs 让 Philippe 的工作得以实现。—— Zach Corleissen

引言

Google Season of Docs 项目汇集了开源组织和技术文档作者，共同密切合作完成一个特定的文档项目。

我被 CNCF 选中参与 Kubernetes 文档工作，特别是让 API 参考文档更易于访问。

我是一名软件开发者，对文档系统有浓厚的兴趣。在 90 年代末，我开始将 Linux-HOWTO 文档翻译成法语。从一件事情到另一件事情，我学到了关于文档系统的知识。最终，我写了一篇 Linux-HOWTO 来帮助文档作者学习当时用于编写文档的语言，即 LinuxDoc/SGML。

不久之后，Linux 文档采用了 DocBook 语言。我帮助一些作者使用这种格式重写了他们的文档；例如，《高级 Bash 脚本指南》(Advanced Bash-Scripting Guide)。我还参与了 GNU 的 makeinfo 程序开发，为其添加 DocBook 输出，使得将 GNU Info 文档转换为 Docbook 格式成为可能。

背景

Kubernetes 网站是使用 Hugo 构建的，文档使用 Markdown 格式编写在网站仓库中，并使用了 Docsy Hugo 主题。

现有的 API 参考文档是一个大型 HTML 文件，由 Kubernetes OpenAPI 规范生成。

就我而言，我一直想让 API 参考文档更易于访问，具体方法包括：

  • 为每个 Kubernetes 资源构建独立自主的页面
  • 使格式适应移动端阅读
  • 重用网站的资产和主题来构建、集成和显示参考页面
  • 允许搜索引擎索引页面的内容

大约一年前，我开始着手修改生成当前唯一 HTML 页面的生成器，添加 DocBook 输出，以便 API 参考文档可以首先生成 DocBook 格式，然后再生成 PDF 或 DocBook 处理器支持的其他格式。最初的成果是一些API 参考电子书文件以及一本自编辑的纸质书。

后来我决定给这个生成器增加另一种输出，生成 Markdown 文件并创建一个包含 API 参考的网站。

当 CNCF 提议了一个 Google Season of Docs 项目，旨在改进 API 参考文档时，我提交了申请，并获得了匹配。

项目内容

swagger-ui

CNCF 成员最初提出这个项目的想法是测试 swagger-ui 工具，尝试使用这个标准工具来记录 Kubernetes API 参考。

由于 Kubernetes API 比许多其他 API 大得多，因此有必要编写一个工具按 API Groups 拆分完整的 API 参考，并在文档网站中插入多个 swagger-ui 组件，每个 API Group 一个。

通常，开发者使用 API 的方式是调用带有特定 HTTP 动词的端点，并携带特定参数等待响应。swagger-ui 界面就是为此类用法设计的：界面显示端点列表及其关联的动词，并展示每个端点的参数和响应格式。

大多数情况下，Kubernetes API 的使用方式有所不同：用户创建包含 YAML 格式资源定义的清单文件，并使用 kubectl 命令行工具将这些清单“应用”到集群。在这种情况下，最重要的信息是用作参数和响应的结构（即 Kubernetes Resources）的描述。

由于这种特殊性，我们意识到很难调整 swagger-ui 界面来满足 Kubernetes API 用户需求，因此放弃了这个方向。

Markdown 页面

项目的第二阶段是将我为创建 k8sref.io 网站所做的工作进行调整，以便将其包含到官方文档网站中。

主要的改变包括：

  • 使用 go-templates 来表示输出页面，这样非开发者无需修改生成器代码即可调整生成页面
  • 创建一个新的自定义短代码，以便在网站内部轻松创建指向 API 参考特定页面的链接
  • 改进 API 参考各部分之间的导航
  • 将生成器代码添加到包含不同参考文档生成器的 Kubernetes GitHub 仓库

所有相关的讨论和完成的工作都可以在网站的pull request #23294 中找到。

将生成器代码添加到 Kubernetes 项目的操作发生在 kubernetes-sigs/reference-docs#179。

以下是新 API 参考文档将包含在官方文档网站中的特性：

  • 资源被分类到工作负载 (Workloads)、服务 (Services)、配置与存储 (Config & Storage)、认证 (Authentication)、授权 (Authorization)、策略 (Policies)、扩展 (Extend)、集群 (Cluster) 等类别。这个结构可以通过一个简单的 toc.yaml 文件进行配置
  • 每个页面都显示第一级的相关资源；例如：Pod、PodSpec、PodStatus、PodList
  • 大多数资源页面内嵌了相关的定义；例外情况是这些定义对于多个资源是通用的，或者过于复杂无法内嵌显示。按照旧方法，你需要点击超链接才能阅读每个额外的细节。
  • 一些广泛使用的定义，例如 ObjectMeta，在特定页面中有文档说明
  • 必填字段有标记，并排在前面
  • 资源的字段可以分类和排序，这得益于一个 fields.yaml 文件
  • map 字段有标记。例如，Pod 的 .spec.nodeSelector 显示为 map[string]string，而不是 object，这是使用了 x-kubernetes-list-type 的值
  • 补丁策略有标记
  • apiVersion 和 kind 显示的是值，而不是 string 类型
  • 在参考页面的顶部，页面会显示从 Go 程序中使用这些资源所需的 Go 导入路径。

该工作目前暂停，等待 1.20 版本发布。发布完成后，这项工作将被集成，API 参考文档将可在 https://kubernetes.ac.cn/docs/reference/ 找到。

未来工作

还有一些可以改进的地方，特别是：

  • 一些 Kubernetes 资源嵌套层级很深。内嵌这些资源的定义会使它们难以理解。
  • 创建的 shortcode 使用页面 URL 来引用资源页面。如果文档作者能够通过资源的组和名称来引用资源，将会更容易。

致谢

我要感谢我的导师 Zach Corleissen 和指导我度过整个季度的主要作者 Karen Bradshaw、Celeste Horgan、Tim Bannister 以及 Qiming Teng。他们都非常鼓励我，并给了我很多很棒的建议。