Rook 文档贡献指南基于 MkDocs Material 的编写、预览与自动生成工作流【免费下载链接】rookStorage Orchestration for Kubernetes项目地址: https://gitcode.com/gh_mirrors/roo/rook本篇指南面向所有希望为 RookKubernetes 存储编排项目贡献文档的开发者。Rook 的官方文档站点由MkDocs与Material for MkDocs主题驱动文档源文件全部位于仓库的Documentation/目录本文将从文档技术栈、Markdown 扩展语法、本地预览、依赖安装到基于make docs/make check.docs的自动生成与质量检查流程系统讲解一套可直接上手、可本地验证的文档贡献工作流。读完本篇你将能在提交 PR 之前独立完成文档编写、本地渲染预览、Chart 文档与 CRD API 参考文档的自动生成并通过仓库自带的检查手段确认文档链接与格式合规。文档技术栈总览Rook 的文档构建方案在 Documentation/Contributing/documentation.md 中定义得非常明确静态站点生成器MkDocs主题Material for MkDocs官方地址squidfunk.github.io/mkdocs-material。这一组合为文档写作带来了两类能力一是开箱即用的漂亮渲染与响应式布局二是 Material 主题内置的“Markdown 语法扩展”让作者可以用更丰富的表达方式来组织技术内容。仓库根目录的 mkdocs.yml 是这一技术栈的实际落地配置其中的关键设定包括docs_dir: Documentation/文档源文件目录所有.md文件都位于该目录下site_name: Rook Ceph Documentation、site_url: https://rook.io站点名称与线上地址use_directory_urls: true使用目录风格的 URL主题启用 Material 的亮/暗双配色切换、导航标签、搜索高亮、即时加载instant等特性插件体系包含search、exclude、awesome-pages、macros、minify、redirects、mike多版本文档等详见下文“构建与发布链路”小节。Markdown 扩展与写作语法得益于 Material for MkDocs 主题文档写作可以使用以下“语法扩展”它们也是 Documentation/Contributing/documentation.md 明确推荐使用的Admonitions提示块用于突出警告、提示、注意等语义化信息。原文档中给出了一处典型用法——当首次预览文档遇到command not found错误时用!!! hint提示块给出解决方案!!! hint Should you encounter a command not found error while trying to preview the docs for the first time on a machine, you probably need to install the dependencies for MkDocs and extensions used: pip3 install -r build/release/requirements_docs.txt. Make sure that your Python binary path is included in your PATH.Footnotes脚注为专业术语或补充说明添加脚注Icons、Emojis图标与表情通过:material-xxx:/:fontawesome-xxx:语法嵌入图标Material 主题将图标渲染为内联 SVGTask lists任务列表配合定义列表definition lists使用适合编写步骤化、可勾选的检查清单以及 Material 参考文档中的更多特性。这些扩展在 mkdocs.yml 的markdown_extensions一节有完整的底层配置例如启用了admonition、attr_list、def_list、footnotes、meta、tables以及pymdownx.details、pymdownx.emoji、pymdownx.highlight、pymdownx.tasklist、pymdownx.tabbed、pymdownx.superfences等一组 PyMdown Extensions。写作时可以直接使用这些语法渲染时即会被正确解析。本地预览文档在仓库根目录执行下面的命令即可启动文档的本地预览服务make docs-preview该命令由 Makefile 中的docs-preview目标提供其实现就是mkdocs serve。启动成功后在浏览器中访问http://127.0.0.1:8000/即可打开本地渲染的文档站点。mkdocs serve会监听文档源文件的变更并自动重建写作过程中刷新浏览器即可看到最新效果非常适合边写边校验。首次预览的依赖安装原文档特别提醒如果在机器上首次执行预览时报command not found说明本机缺少 MkDocs 及其扩展依赖需要先安装 build/release/requirements_docs.txt 中列出的 Python 包pip3 install -r build/release/requirements_docs.txt并确保 Python 的 bin 目录已被加入PATH。该文件是文档构建的“依赖清单”当前内容包含mike mkdocs mkdocs-awesome-pages-plugin mkdocs-exclude mkdocs-macros-plugin mkdocs-material mkdocs-material-extensions mkdocs-minify-plugin mkdocs-redirects pygit2其中mike用于文档多版本管理mkdocs-awesome-pages-plugin负责目录自动排序mkdocs-macros-plugin提供模板宏能力mkdocs.yml 中macros.module_name: .docs/macros/includes/mainmkdocs-minify-plugin用于压缩 HTML/JS 产物mkdocs-redirects用于配置页面重定向mkdocs.yml 中已为README.md等配置了redirect_maps。若需要构建而非仅预览还可以使用make docs-build对应mkdocs build --strict见 Makefile它会以严格模式构建到site/目录任何告警都会导致失败适合在 CI 中把关。自动生成文档Chart 文档与 CRD API 参考Rook 的Documentation/下存在两类“机器生成”的文档Helm Chart 文档与 CRD API 参考文档。它们不应手工编辑而是由 Makefile 目标驱动生成器自动产出。用 helm-docs 生成 Helm Chart 文档make docsDocumentation/Contributing/documentation.md 明确指出helm-docs是一个自动为 Helm Chart 生成文档的工具只要 Chart 发生变化开发者就需要运行make docs并将自动生成的文件一并提交。make docs目标的实现Makefile会针对两个 Chart 分别执行 helm-docshelm-docs: $(HELM_DOCS) ## Use helm-docs to generate documentation from helm charts $(HELM_DOCS) -c deploy/charts/rook-ceph \ -o ../../../Documentation/Helm-Charts/operator-chart.md \ -t ../../../Documentation/Helm-Charts/operator-chart.gotmpl.md \ -t ../../../Documentation/Helm-Charts/_templates.gotmpl $(HELM_DOCS) -c deploy/charts/rook-ceph-cluster \ -o ../../../Documentation/Helm-Charts/ceph-cluster-chart.md \ -t ../../../Documentation/Helm-Charts/ceph-cluster-chart.gotmpl.md \ -t ../../../Documentation/Helm-Charts/_templates.gotmpl也就是说输入deploy/charts/rook-ceph与deploy/charts/rook-ceph-cluster两个 Chart 目录输出Documentation/Helm-Charts/operator-chart.md与Documentation/Helm-Charts/ceph-cluster-chart.md模板operator-chart.gotmpl.md、ceph-cluster-chart.gotmpl.md及公共模板_templates.gotmpl。helm-docs 工具本身由 build/makelib/helm.mk 负责安装固定版本为HELM_DOCS_VERSION : v1.11.0通过go install github.com/norwoodj/helm-docs/cmd/helm-docsv1.11.0构建到本地工具目录。这也是make gen.docs/make gen.helm-docs同义目标的最终落点。以 Documentation/Helm-Charts/operator-chart.gotmpl.md 为例模板头部通过{{ template generatedDocsWarning . }}引入“自动生成”警示横幅正文是 Chart 的安装方式、参数表格等结构这些内容最终被 helm-docs 依据 Chart 的values.yaml渲染进operator-chart.md。因此修改 Chart 的 values 后必须重新生成文档保证参数文档与实际 Chart 一致。生成 CRD API 参考文档make crds.docs / make gen.crd-docs除 Helm Chart 文档外仓库还提供了 CRD API 参考文档的生成链路。执行make crds.docs或等价的make gen.crd-docs会调用 build/crds/generate-crd-docs.sh。该脚本的核心逻辑是安装生成器github.com/ahmetb/gen-crd-api-reference-docs固定版本v0.3.0以 build/crds/crd-docs-config.json 为配置、Documentation/gen-crd-api-reference-docs/template为模板目录对github.com/rook/rook/pkg/apis/ceph.rook.io这个 API 包执行生成输出到Documentation/CRDs/specification.md。脚本还支持SKIP_GEN_CRD_DOCStrue环境变量来跳过生成默认行为是每次都重新生成。由此可知Documentation/CRDs/下各 CRD 文档如 ceph-cluster-crd.md与specification.md均源自pkg/apis/ceph.rook.io/v1中的 Go 类型定义与注释——修改 API 类型后需要同步更新这些文档。提交前自检make check.docs为了便于本地检查“自动生成文档是否被同步更新”Documentation/Contributing/documentation.md 强调存在一个额外的 Make 目标make check.docs该目标会运行文档自动生成流程如果生成了与仓库中已提交内容不一致的变更就会报错提示。因此原文档建议在创建或更新 PR 之前养成先本地运行make check.docs的习惯确保生成的文档文件与当前源码保持一致避免在 CI 中被拦截。文档质量检查链路除了自动生成仓库还配套了一组文档质量检查工具共同保证Documentation/的链接与格式质量内部链接检查tests/scripts/check-markdown-links-internal.sh 使用markdown-link-check配置见 tests/scripts/mlc_config.json遍历Documentation/下所有*.md文件并额外检查AGENTS.md——因为该文件几乎全由指向Documentation/的链接构成失效链接会静默误导读者。脚本会汇总“检查文件数 / 通过数 / 失效数”并给出清晰的成功或失败结论。这意味着贡献者应保证文档中的相对链接真实可达。Markdown 格式校验仓库在 tests/scripts 下提供了两个 markdownlint 自定义规则markdownlint-admonitions.js强制 MkDocs admonitions 使用正确的格式markdownlint-tab-spacing.js校验缩进对齐确保有序/无序列表与代码块的缩进符合 MkDocs 的渲染预期该文件注释明确提到 MkDocs 的渲染对缩进敏感建议缩进对齐到 4 空格边界。严格构建make docs-build即mkdocs build --strict在 CI 与本地均可作为最终闸门任何无效引用或构建告警都会以失败告终。这些工具与 Documentation/Contributing/documentation.md 描述的make docs-preview、make docs、make check.docs共同构成了一套完整的“写作 → 预览 → 生成 → 校验”闭环。文档贡献流程小结综合原文档与仓库实现向 Rook 贡献文档的推荐流程如下定位源文件所有文档源文件位于 Documentation 目录站点导航由mkdocs.yml结合awesome-pages插件驱动注意mkdocs.yml的exclude插件会排除README.md与*.gotmpl/*.gotmpl.md因此这些文件不会进入最终站点如各 Chart 的README.md与Documentation/Helm-Charts下的*.gotmpl.md模板。本地预览在仓库根目录运行make docs-preview浏览器打开http://127.0.0.1:8000/实时查看渲染效果若缺依赖先执行pip3 install -r build/release/requirements_docs.txt。遵循扩展语法使用 Admonitions、脚注、任务列表、图标等 Material 扩展组织内容保证链接使用相对路径且真实可达。同步自动生成文档若修改了deploy/charts/rook-ceph、deploy/charts/rook-ceph-cluster等 Chart运行make docs重新生成 Documentation/Helm-Charts 下的 Chart 文档若修改了pkg/apis/ceph.rook.io中的 CRD 类型运行make crds.docs重新生成 Documentation/CRDs/specification.md。提交前自检运行make check.docs确认没有遗漏的自动生成变更并通过链接检查脚本与 markdownlint 校验后再创建或更新 PR。这一流程既适用于新增一篇独立指南如 Storage-Configuration 下的功能说明也适用于对现有 Documentation 各子目录Getting-Started、Storage-Configuration、Troubleshooting、Upgrade、Helm-Charts 等的增量修改。遵循该流程可以确保文档与源码、Chart、CRD 始终保持一致让文档站点长期可靠、可维护。【免费下载链接】rookStorage Orchestration for Kubernetes项目地址: https://gitcode.com/gh_mirrors/roo/rook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考