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
  • 指出了补丁策略
  • apiVersionkind 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), 蒂姆·班尼斯特滕启明 整个赛季都在监督我他们都很令人鼓舞,并给了我很多建议。