基于 gen-crd-api-reference-docs 自动生成 Prometheus Operator CRD API 参考文档【免费下载链接】prometheus-operatorPrometheus Operator creates/configures/manages Prometheus clusters atop Kubernetes项目地址: https://gitcode.com/gh_mirrors/pr/prometheus-operator本文介绍 Prometheus Operator 仓库中scripts/docs目录的作用与用法它保存了生成 Prometheus Operator 自定义资源CRDHTML/Markdown API 参考文档所需的配置与 Go 模板通过外部工具gen-crd-api-reference-docs从pkg/apis/monitoring的 Go 类型源码自动生成文档。读者读完本文后可以了解文档生成链路的配置方式、模板结构、产物位置并掌握如何在本地重新生成这些 API 参考文档。目录定位与核心作用Prometheus Operator 的 API 参考文档并非手工编写而是由源码自动生成的。负责这一任务的目录是 scripts/docs它包含两个核心组成部分README.md说明目录用途与构建方法config.jsongen-crd-api-reference-docs的配置控制哪些字段、类型与包被渲染以及外部类型的链接指向哪里templates/三份 Go 文本模板pkg.tpl、type.tpl、members.tpl决定最终文档的排版结构。这些文件共同把pkg/apis/monitoring下的 Go 类型定义转换成可读的 API 参考手册最终产物即仓库中的 Documentation/api-reference/api.md约 4 万余行的生成文件涵盖monitoring.coreos.com/v1、v1alpha1、v1beta1三个 API 组。整个链路使用的生成工具是外部开源项目 gen-crd-api-reference-docs该工具从 Go 源码与 CRD 结构生成 API 参考文档。Prometheus Operator 的 Makefile 中将其作为工具依赖引入# Makefile API_DOC_GEN_BINARY$(TOOLS_BIN_DIR)/gen-crd-api-reference-docs构建方式一条 make 命令原文档给出了最直接的构建方法在仓库顶层目录执行make --always-make generate-docs其中--always-make强制忽略时间戳依赖、无条件重新执行目标。在 Makefile 中generate-docs目标定义为.PHONY: generate-docs generate-docs: $(shell find Documentation -type f) ## Generate operator documentation.从定义看该目标依赖Documentation目录下的所有文件——这保证了在文档模板、CRD 配置或 API 类型发生变化时generate-docs会感知到相关变更并重新生成。与此同时generate-docs也被纳入顶层聚合目标generategenerate: k8s-gen generate-crds generate-metrics bundle.yaml example/mixin/alerts.yaml example/thanos/thanos.yaml example/admission-webhook example/alertmanager-crd-conversion generate-docs image-builder-version ## Generate all files (CRDs, client-go libraries, docs, etc.).也就是说执行make generate时同样会触发 API 文档的重新生成。配置详解config.jsonscripts/docs/config.json 是文档生成行为的核心配置主要包含以下字段。hideMemberFields 与 hideTypePatternshideMemberFields: [ TypeMeta ], hideTypePatterns: [ ParseError$, List$, Interface$ ]hideMemberFields隐藏指定名称的成员字段。这里隐藏了所有类型的TypeMeta即Kind、apiVersion这两个通用元数据字段因为该信息由模板以apiVersion/kind行固定渲染无需在成员表中重复出现见下文模板部分hideTypePatterns按正则表达式隐藏整类类型。规则分别为隐藏所有以ParseError结尾的类型解析错误类型、以List结尾的类型*List资源列表类型、以Interface结尾的类型接口类型。这三类类型不直接面向用户隐藏后能显著精简文档。对应地templates/members.tpl 中的hiddenMember判断与hideMemberFields配置配合跳过被隐藏的成员templates/pkg.tpl 则通过visibleTypes函数过滤出可见类型进行渲染。externalPackages外部类型的链接策略externalPackages: [ { typeMatchPrefix: ^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$, docsURLTemplate: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration }, { typeMatchPrefix: ^k8s\\.io/apimachinery/pkg/util/intstr\\.IntOrString$, docsURLTemplate: https://pkg.go.dev/k8s.io/apimachinery/pkg/util/intstr#IntOrString }, { typeMatchPrefix: ^k8s\\.io/apimachinery/pkg/api/resource\\.Quantity$, docsURLTemplate: https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity }, { typeMatchPrefix: ^k8s\\.io/(api|apimachinery/pkg/apis)/, docsURLTemplate: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}} }, { typeMatchPrefix: ^k8s\\.io/apiextensions-apiserver/pkg/apis/apiextensions/v1\\.JSON$, docsURLTemplate: https://pkg.go.dev/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1#JSON }, { typeMatchPrefix: ^github\\.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1, docsURLTemplate: ../v1/api.md#monitoring.coreos.com/v1.{{ .TypeIdentifier}} }, { typeMatchPrefix: ^github\\.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1alpha1, docsURLTemplate: ../v1alpha1/api.md#monitoring.coreos.com/v1alpha1.{{ .TypeIdentifier}} }, { typeMatchPrefix: ^github\\.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1beta1, docsURLTemplate: ../v1beta1/api.md#monitoring.coreos.com/v1beta1.{{ .TypeIdentifier}} } ]配置要点使用typeMatchPrefix正则前缀匹配判断类型归属用docsURLTemplate指定该类型出现时的链接模板Kubernetes 基础类型k8s.io/api、k8s.io/apimachinery/pkg/apis、Duration、IntOrString、Quantity、apiextensions/v1.JSON统一链接到外部权威文档避免在生成的文档里重复展开这些通用类型项目内部的monitoring.coreos.com/v1、v1alpha1、v1beta1类型则链接到同仓库的 API 参考文档锚点形如#monitoring.coreos.com/v1.Prometheus实现组内类型互链。注意这里的链接模板../v1/api.md#...是相对生成工具输出位置的写法最终会体现为 Documentation/api-reference/api.md 中包内的锚点互链模板中还内置了{{arrIndex .PackageSegments -1}}、{{lower .TypeIdentifier}}之类的模板函数用于在生成 Kubernetes API 文档链接时拼装路径段如资源类型名、API 组名这是 gen-crd-api-reference-docs 提供的模板能力。typeDisplayNamePrefixOverrides 与 markdownDisabledtypeDisplayNamePrefixOverrides: { k8s.io/api/: Kubernetes , k8s.io/apimachinery/pkg/apis/: Kubernetes , github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1: Monitoring v1, github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1alpha1: Monitoring v1alpha1, github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1alpha1: Monitoring v1beta1 }, markdownDisabled: falsetypeDisplayNamePrefixOverrides将类型全名的指定前缀替换为更易读的显示名。例如github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1.Prometheus显示为Monitoring v1.PrometheusKubernetes 类型显示为Kubernetes xxxmarkdownDisabled: false允许生成 Markdown而非仅 HTML这正是仓库中 Documentation/api-reference/api.md 的产出格式需要留意的是配置中存在两处v1alpha1键第二处按内容推断本意应为v1beta1属于配置文件中的一个既有笔误不影响正文使用这里如实指出。模板结构pkg.tpl / type.tpl / members.tpl模板目录 scripts/docs/templates/ 存放三份 Go 模板采用define定义具名模板的方式组织模板文件定义的模板职责pkg.tplpackages文档整体骨架front matter、包列表、资源类型目录与逐包渲染type.tpltype单个类型的渲染标题、出现在哪些类型上Appears on、注释、常量表、字段表members.tplmember/members类型成员字段的递归渲染与字段表pkg.tpl包与资源类型总览templates/pkg.tpl 首先输出 Hugo 风格的 front matter--- title: API reference description: Prometheus operator generated API reference docs draft: false images: [] menu: operator weight: 151 toc: true ---然后在文档顶部声明此页面由gen-crd-api-reference-docs自动生成接着渲染三个 API 组的锚点索引最后对每个包用packageDisplayName输出包名锚点如monitoring.coreos.com/v1渲染包的 DocComments来自pkg/apis/monitoring对应包的 Go 注释列出该包下的资源类型Resource Types即直接面向用户的 CRD 顶层类型对每个可见类型递归调用type模板。例如 Documentation/api-reference/api.md 中monitoring.coreos.com/v1一节的资源类型列表包含Alertmanager、PodMonitor、Probe、Prometheus、PrometheusRule、ServiceMonitor、ThanosRuler。type.tpl单个类型的字段表templates/type.tpl 对每个类型输出以h3标题给出类型名若是Alias类型则标注其底层类型Appears on列表列出该类型被哪些其他类型引用由typeReferences函数计算类型的 Go 文档注释renderComments渲染若类型定义了常量输出Value / Description常量表constantsOfType若类型有成员输出字段表并对导出类型固定渲染apiVersion与kind两行其值分别来自apiGroup与类型名——这也解释了为什么config.json中要隐藏TypeMeta字段避免重复展示对spec字段模板会递归展开其子字段表见下。members.tpl字段的递归渲染templates/members.tpl 是字段渲染的核心member模板先检查hiddenMember对应配置里的hideMemberFields被隐藏则跳过对于内嵌字段fieldEmbedded如 Go 结构体中内嵌的metav1.ObjectMeta、*PrometheusSpec等会递归展开其所有成员形成平铺的字段表每个字段输出字段名fieldName、类型若该类型有链接则输出链接、(Optional)标记isOptionalMember判断对应 Go 的omitemptytag、字段注释对ObjectMeta类型给出固定提示Refer to the Kubernetes API documentation for the fields of themetadatafield.对名为spec的字段递归输出其子结构体成员的嵌套字段表让spec的详细配置直接在父类型页面内展开方便阅读。从实现上看这套模板依赖 gen-crd-api-reference-docs 提供的模板函数packageAnchorID、packageDisplayName、typeDisplayName、linkForType、visibleTypes、sortedTypes、isExportedType、typeReferences、constantsOfType、renderComments、fieldEmbedded、hiddenMember、isOptionalMember等。数据来源pkg/apis/monitoring 与产物验证生成器解析的事实来源是 API 类型定义所在的 Go 包 pkg/apis/monitoringv1稳定版本 API包含Prometheus、Alertmanager、ServiceMonitor、PodMonitor、Probe、PrometheusRule、ThanosRuler等核心 CRD 类型v1alpha1alpha 版本 API包含如ScrapeConfig、PrometheusAgent等演进中的类型v1beta1beta 版本 API包含AlertmanagerConfig等类型。每个类型的 DocComment、字段注释、omitempty标记都会原样进入生成文档因此撰写这些 Go 注释的质量直接决定了 API 文档的质量。例如生成产物中Alertmanager类型的开篇描述即来自其 Go 源码注释defines a desired Alertmanager setup to run in a Kubernetes cluster ...并注明部署StatefulSet、多副本高可用等行为。生成产物 Documentation/api-reference/api.md 的页首同样标注 This page is automatically generated withgen-crd-api-reference-docs与模板的约定一致可以作为文档由该链路生成的直接证据。生成的api.md通过 Documentation/api-reference 目录暴露给读者而项目根目录的 README.md 与文档体系也会引用这份 API 参考。与文档生成链路的其他环节generate-docs只是 Prometheus Operator 整个代码生成体系的一环。在 Makefile 的generate聚合目标中它与其他生成步骤并列k8s-gen生成 client-go 风格的 applyconfiguration、informers、listers 等对应 pkg/clientgenerate-crds从 jsonnet 生成 CRD YAML对应 example/prometheus-operator-crd/generate-metrics从 API marker 生成 Prometheus condition collector 代码bundle.yaml、example/...生成部署清单与示例generate-docs生成本文所述的 API 参考文档。另外cmd/po-docgen 中的compatibility子命令make compatibility相关工具用于从pkg/apis/monitoring的兼容性矩阵生成版本支持列表与 API 文档生成同属文档/元数据自动化方向但它走的是独立的po-docgen工具链不依赖 gen-crd-api-reference-docs两者不要混淆。常见问题与使用建议文档与源码不一致怎么办API 文档由源码自动生成修改类型字段、注释后必须重新执行make --always-make generate-docs使产物同步不要手工编辑 Documentation/api-reference/api.md。如何自定义隐藏字段/类型修改 scripts/docs/config.json 中的hideMemberFields精确字段名与hideTypePatterns正则支持$锚点如List$即可。如何调整文档排版编辑 scripts/docs/templates/ 下的三份.tpl文件注意模板依赖 gen-crd-api-reference-docs 内置的模板函数修改前先确认函数签名与渲染逻辑。外部类型为何没有详细展开这是externalPackages的设计意图Kubernetes 基础类型一律链接到权威外部文档pkg.go.dev或 Kubernetes API 参考避免在仓库内重复维护大量样板内容同时保证链接长期有效。产物在哪里查看生成的完整 API 参考位于 Documentation/api-reference/api.md覆盖monitoring.coreos.com/v1、v1alpha1、v1beta1三个 API 组可按包名锚点快速定位到任意资源类型如Prometheus、ServiceMonitor、AlertmanagerConfig。小结Prometheus Operator 的 CRD API 参考文档遵循源码即文档的工程实践Go 类型注释作为唯一事实来源gen-crd-api-reference-docs作为生成引擎scripts/docs/config.json 控制渲染范围与外部链接scripts/docs/templates/ 控制排版结构最终由make generate-docs产出 Documentation/api-reference/api.md。理解这条链路无论是维护 API 注释、调整文档生成配置还是排查文档与代码不一致的问题都能做到有的放矢。【免费下载链接】prometheus-operatorPrometheus Operator creates/configures/manages Prometheus clusters atop Kubernetes项目地址: https://gitcode.com/gh_mirrors/pr/prometheus-operator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考