GSoD 2020：改善API参考体验

作者: 菲利普·马丁

编者注：自三年半前加入Kubernetes文档以来，更好的API引用一直是我的目标。 Philippe取得了惊人的成功。但是，Philippe不仅提供了更好的API参考，还体现了Kubernetes社区在该项目中的优势：通过协作实现了卓越，以及使社区本身变得更好的过程。感谢Google文件季，使Philippe的工作成为可能。 —扎克·科里森（Zach Corleissen）

介绍

的 Google文件季 该项目将开放源代码组织和技术作家召集在一起，以紧密地致力于特定的文档项目。

我被CNCF选择来从事Kubernetes文档的工作，特别是为了使API参考文档更易于访问。

我是一位对文档系统非常感兴趣的软件开发人员。在90年代后期，我开始将Linux-HOWTO文档翻译成法语。从一件事到另一件事，我了解了文档系统。最终，我写了一个Linux-HOWTO帮助文档管理员学习当时用于编写文档的语言LinuxDoc / SGML。

Shortly afterward, Linux documentation adopted the DocBook language. I helped some writers rewrite their documents in this format; for example, the Advanced Bash-Scripting Guide. I also worked on the GNU makeinfo program to add DocBook output, making it possible to transform GNU资讯 文档转换成Docbook格式。

背景

的 Kubernetes网站 是由Hugo用Markdown格式编写的文档在 网站资料库， 使用 Docsy Hugo主题.

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

在我这边，我想花些时间通过以下方式使API参考更易于访问：

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

大约一年前，我开始使用生成器来构建当前唯一的HTML页面，以添加DocBook输出，因此可以首先以DocBook格式生成API参考，然后以PDF或DocBook处理器支持的其他格式生成API参考。第一个结果是 适用于API参考的电子书文件 和一本自动编辑的纸质书。

后来我决定将另一个输出添加到此生成器，以生成Markdown文件并创建 具有API参考的网站.

当CNCF为Google文件季提出一个可以在API Reference上运行的项目时，我申请了，结果发生了匹配。

该项目

swagger-ui

提议该项目的CNCF成员的第一个想法是测试 swagger-ui 工具，以尝试使用此标准工具记录《 Kubernetes API参考》。

Because the Kubernetes API is much larger than many other APIs, it has been necessary to write a 工具 to split the complete API Reference by API Groups, 和 insert in the 文献资料 website several swagger-ui components, one for each API Group.

Generally, APIs are used by developers by calling endpoints with a specific HTTP verb, with specific parameters 和 waiting for a response. 的 swagger-ui interface is built for this usage: the interface displays a list of endpoints 和 their associated verbs, 和 for each the parameters 和 responses formats.

的 Kubernetes API is most of the time used differently: users create manifest 文件s containing resources definitions in YAML format, 和 use the kubectl CLI to 应用 这些体现在集群上。在这种情况下，最重要的信息是对用作参数和响应的结构的描述（Kubernetes资源）。

Because of this specificity, we realized that it would be difficult to adapt the swagger-ui interface to satisfy the users of the Kubernetes API 和 this direction has been abandoned.

降价页面

该项目的第二阶段是适应我创建k8sref.io网站所做的工作，以将其包含在官方文档网站中。

主要更改为：

  • 使用go-templates表示输出页面，因此非开发人员可以修改生成的页面而无需编辑生成器代码
  • 创建一个新的自定义 短代码，以轻松创建从网站内部到API参考特定页面的链接
  • 改善API参考各节之间的导航
  • 将生成器的代码添加到包含不同参考生成器的Kubernetes GitHub存储库中

所有讨论和完成的工作都可以在网站上找到 拉取请求＃23294.

生成器代码添加到Kubernetes项目中发生在 kubernetes-sigs / reference-docs＃179.

以下是官方文档网站中将包含的新API参考的功能：

  • 资源按工作负载，服务，配置和存储，身份验证，授权，策略，扩展，群集类别进行分类。该结构可通过简单的方式配置 toc.yaml 文件
  • 每个页面在第一层显示相关的资源;例如：Pod，PodSpec，PodStatus，PodList
  • 大多数资源页面内联相关定义;例外情况是这些定义是几种资源所共有的，或者过于复杂而无法内联显示。使用旧方法时，您必须遵循超链接才能阅读每个额外的细节。
  • some widely used definitions, such as ObjectMeta, are documented in a specific page
  • 显示必填字段，并放在最前面
  • 资源的字段可以通过以下方式进行分类和排序 fields.yaml 文件
  • map fields are indicated. For example the .spec.nodeSelector for a Pod is map[string]string, instead of object， 使用 value of x-kubernetes-list-type
  • 指出了补丁策略
  • apiVersion 和 kind display the value, not the string type
  • 在参考页面的顶部，该页面显示使用Go程序中的这些资源所需的Go导入。

该工作目前在1.20版本中搁置。发布完成并完成工作整合后，可以在以下位置获得API参考： //sjzrbxc.cn/docs/reference/.

未来的工作

有一些要改进的地方，尤其是：

  • 一些Kubernetes资源被深深地嵌套。内联这些资源的定义使它们难以理解。
  • 的 created 短代码 uses the URL of the page to reference a Resource page. It would be easier for documentarians if they could reference a Resource by its group 和 name.

升值

我要感谢我的导师 扎克·科莱森（Zach Corleissen） 和主要作家 凯伦·布拉德肖（Karen Bradshaw）, 塞莱斯特·霍根（Celeste Horgan）, 蒂姆·班尼斯特 和 滕启明 整个赛季都在监督我他们都很令人鼓舞，并给了我很多建议。