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），仅供参考
企业数字化 ERP 产品动态
相关推荐
别被同步听官网坑了，3个维度讲透性能优化选型 别被同步听官网坑了，3个维度讲透性能优化选型 面试时考官问：“你们系统里那个‘同步听’功能，为什么高并发下会卡死？底层原理是什么？” 你如果只会说“用了 WebSocket 或者长轮询”，基本就挂了。… · 2026/9/23 2:17:32
高德地图API批量距离计算工具：Java多线程实现物流距离矩阵 简介：面向物流、配送及地理信息处理开发者，这套基于高德地图API的Java工具专门解决批量地理位置距离计算问题，支持地址批量输入、距离矩阵计算、CSV文件导入导出、多线程并发处理与结果可视化展示，适合需要处理成百上千个地址数据… · 2026/9/23 2:17:26
swagger-codegen 生成的 Dart/Flutter Pet 模型完全指南：字段结构、JSON 序列化与源码级解析 开发工具代码生成API设计 【免费下载链接】swagger-codegen swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition. 项目地址： http… · 2026/9/23 2:17:26
多平台智能客服系统实战：消息总线、验签与幂等的架构设计 简介：基于大模型的智能对话客服工具源码包，面向需要统一管理多平台私信与客户咨询的运营人员、客服团队及开发者，可显著提升多平台响应效率。工具覆盖微信、千牛、哔哩哔哩、抖音企业号、抖音、抖店、微博、小红书、知乎等主流平台࿰… · 2026/9/23 5:19:15
WeKnora深度拆解：从RAG问答到企业知识自进化框架实战 从 RAG 问答到 Wiki 自进化，WeKnora 这个项目确实值得花一天时间好好拆解。它是腾讯开源的企业级知识框架，解决的是企业内部知识散落、大模型幻觉、知识不更新这些老大难问题。如果你正在做知识库、智能问答、企业内部 Wiki 增强，或者想了解 … · 2026/9/23 5:19:15
机器人+AI工业应用落地指南：从ROS2、视觉引导到VDA5050的工程实践 简介：这份《2025年机器人人工智能工业应用研究报告》面向制造业从业者、工业自动化研究者及关注AI落地趋势的技术管理者，系统梳理“机器人人工智能”在工业场景中的技术演进与产业实践。报告从技术突破、大国竞争与市场前景三个角度切入，回顾… · 2026/9/23 5:19:15
柯美C6100/6085故障排除：周期定位与转印调整实战指南 简介：面向柯美C6100-6085多功能一体机的故障排除手册，专为维修工程师、技术员及关注设备维护的普通用户编写，提供标准化诊断与修复流程，覆盖图像质量、纸张输送、传动带、墨粉等高频故障模块。图像质量篇针对圆点、白点、鱼眼效应… · 2026/9/23 5:19:15
无人机红外目标检测：YOLOv13与Django的工程实践 1. 项目背景与核心价值无人机搭载红外摄像头进行目标检测是近年来计算机视觉领域的热门应用方向。相比传统可见光摄像头，红外成像具有全天候工作能力，不受光照条件限制，在夜间监控、森林防火、电力巡检等场景中展现出独特优势。而YOLOv13作为… · 2026/9/23 5:19:09
3招搞定手机怎么下载微信面试难题实战项目解析 3招搞定手机怎么下载微信面试难题实战项目解析 面试被问“手机怎么下载微信”背后的原理，90%的人答不上来。别笑，这看似弱智的问题，实则是考察你对移动应用分发机制、安全校验及网络协议理解的试金石。我带过不少校招新人，他们背了八股文，却连一个A… · 2026/9/23 0:00:03
你有新短消息请注意查收：3个新手避坑指南搞定消息系统选型 你有新短消息请注意查收：3个新手避坑指南搞定消息系统选型 面试被问“高并发下如何保证消息不丢失”，你张口就是“用Redis”，结果面试官追问“如果Redis宕机了怎么办”，你瞬间卡壳。这种场景太常见了，很多新手在背八股文时，只记住了技术名词… · 2026/9/23 0:00:29
