数据湖湖仓一体大数据【免费下载链接】icebergApache Iceberg项目地址https://gitcode.com/gh_mirrors/iceberg5/iceberg点击查看免费下载本文以 Apache Iceberg 仓库中的 site/README.md 为线索系统梳理 Iceberg 官网非版本化静态站点与版本化文档docs/docs/如何基于 MkDocs 与mkdocs-monorepo-plugin完成“一次构建、多版本聚合”的全过程。读者将掌握仓库中site/与docs/两个目录的职责划分、make build / serve / clean / deploy等常用工作流、orphan 分支与 git worktree 挂载机制以及贡献者编写文档时必须遵守的链接规范从而能够独立搭建本地文档环境并参与 Iceberg 文档维护。站点全貌一个仓库两种站点一次构建Apache Iceberg 的站点工程位于仓库根目录下的 site/ 子项目中它同时承载两类内容非版本化站点site位于 site/docs/存放about.md、spec.md、view-spec.md、puffin-spec.md、multi-engine-support.md等不随版本变化的页面版本化文档docs位于仓库根目录 docs/docs/存放随 Iceberg 版本演进的内容例如branching.md、configuration.md、spark-queries.md、flink-ddl.md、table-migration.md等。如 site/README.md 所述site/docs目录之所以这样命名是为了遵循 MkDocs 的docs_dir约定详见下文而仓库根部的/site与/docs恰好与 MkDocs 的默认命名一致但两者之间并没有直接对应关系——这是阅读本工程时最容易混淆、也最需要先厘清的一点。. ├── docs (versioned) │ ├── docs │ │ ├── assets │ │ ├── api.md │ │ ├── ... │ │ └── table-migration.md │ └── mkdocs.yml └── site (non-versioned) ├── docs │ ├── about.md │ ├── ... │ └── view-spec.md ├── ... ├── Makefile ├── mkdocs.yml └── requirements.txt“一个仓库、两种站点”最终通过一个聚合插件合并为统一的 Apache Iceberg 站点顶层 site/mkdocs.yml 中启用了monorepo插件并在 site/nav.yml 中通过!include指令把各版本文档的mkdocs.yml织入顶层导航当前仓库状态下列出了nightly、latest、1.5.2至1.4.0等版本入口。这也正是 README 中“所有子站点被编织在一起用一次构建产出最终站点”的实现基础。构建基础MkDocs 关键概念与工程配置在深入构建流程前需要掌握 MkDocs 的三个基础概念对应 site/README.md 的 “MkDocs background” 一节docs_dir指向 MkDocs 项目 Markdown 源文件所在目录默认是mkdocs.yml同级的docs目录mkdocs build执行静态站点构建的命令site_dir构建产物的输出目录构建后它成为生成站点的根目录站内所有内部链接都以它为基准进行解析。Iceberg 的两个 MkDocs 项目配置各有侧重顶层站点site/mkdocs.yml使用material主题开启navigation.tabs、search.suggest、search.highlight、content.code.copy、offline等 feature插件栈为search、macros、monorepo、privacy以及受环境变量控制的offline同时通过extra注入icebergVersion: 1.5.2、nessieVersion、flinkVersion等宏变量供页面模板使用版本化文档docs/mkdocs.yml结构更轻仅启用search插件site_name形如docs/latest并在导航中直接聚合 Spark、Flink、Hive、AWS、Nessie 等各引擎的使用指南。依赖则统一锁定在 site/requirements.txt 中核心包括mkdocs-material9.5.27 mkdocs-monorepo-plugin githttps://github.com/bitsondatadev/mkdocs-monorepo-pluginurl-fix mkdocs-macros-plugin1.0.5 mkdocs-awesome-pages-plugin2.9.2 mkdocs-redirects1.2.1 mkdocs-material-extensions1.3.1环境要求为Python 3.9 与 pip见 site/README.md 的 Requirements 一节。版本化文档的获取orphan 分支与 git worktree 挂载版本化文档并不直接存放在main分支中而是提交在两个独立的 orphan 分支上site/README.md 的 “Building the versioned docs” 一节docs分支保存各 release 时点的文档源文件即/docs目录快照构建时被挂载到/site/docs/docs/versionjavadoc分支保存历次静态生成的 Javadoc构建时被挂载到/site/docs/javadoc/version。构建阶段通过git worktree将这两个分支“借”到本地具体逻辑集中在 site/dev/common.sh 的pull_versioned_docs函数中create_or_update_docs_remotesite/dev/common.sh检查是否存在名为iceberg_docs的 remote不存在则添加并执行git fetchgit worktree add分别挂载docs与javadoc分支到docs/docs与docs/javadocget_latest_versionsite/dev/common.sh按数字目录排序sort -V找出最新版本号create_latestsite/dev/common.sh为latest建立指向最新版本目录的软链接并复制对应mkdocs.ymlcreate_nightlysite/dev/common.sh为nightly建立指向当前仓库/docs的软链接代表“未发布的最新文档”。构建完成后site/docs下会生成如下结构README 中的示意latest与nightly均为符号链接./site/ └── docs ├── docs │ ├── nightly (symlink to /docs/) │ ├── latest (symlink to /site/docs/1.4.0/) │ ├── 1.4.0 │ ├── 1.3.1 │ └── ... ├── javadoc │ ├── nightly (currently points to latest) │ ├── latest │ ├── 1.4.0 │ ├── 1.3.1 │ └── ... └── .asf.yaml其中nightly指向当前仓库根目录 docs/ 的实时状态latest指向docs分支中按 semver 排序的最新版本.asf.yaml则通过git show ${REMOTE}/main:../.asf.yaml从远端抽取见 site/dev/setup_env.sh。此外search_exclude_versioned_docssite/dev/common.sh还会向各版本页面的 front matter 注入search: exclude: true避免版本化文档干扰站点搜索索引。Makefile 工作流build / serve / clean / deploy / help顶层 site/Makefile 定义了五个 recipe逐一对应 site/dev/ 下的脚本Recipe说明实际执行help打印各 recipe 的帮助信息从 Makefile 中解析#注释并格式化输出build清理并本地构建站点dev/build.shclean清理本地构建产物dev/clean.shdeploy清理、构建并部署 Iceberg 文档站点dev/deploy.shserve清理、构建并在本地运行站点dev/serve.sh本地构建make buildmake build实际调用 site/dev/build.sh其核心是先执行./dev/setup_env.sh该脚本会清理旧产物、安装依赖、挂载版本化文档 worktree 并生成latest/nightly软链接随后运行mkdocs build。本地预览make servemake serveserve同样先执行setup_env.sh完成脚手架再调用mkdocs serve --dirty --watch .见 site/dev/serve.sh站点默认运行在http://localhost:8000。--dirty与--watch配合可实现改文件即增量重载适合日常文档编写调试。清理产物make cleanmake cleansite/dev/clean.sh 调用 site/dev/common.sh 中的clean函数先临时关闭set -e删除docs/docs/latest、docs/docs/nightly软链接通过git worktree remove摘除docs/docs与docs/javadoc两个 worktree最后清空docs/javadoc、docs/docs、docs/.asf.yaml与site/构建产物目录。部署上线make deploymake deploysite/dev/deploy.sh 在setup_env.sh之后执行mkdocs gh-deploy --no-history --remote-branchasf-site将构建结果发布到asf-site分支不保留历史。这一步是发布流程的第二阶段详见下文。离线模式无需服务器的本地阅读MkDocs Material 主题自带的 offline 插件允许用户直接从本地文件系统打开文档而无需启动服务器site/README.md 的 “Offline mode” 一节。Iceberg 通过OFFLINE环境变量开启该能力可作用于build或servemake build OFFLINEtrue从配置层面看site/mkdocs.yml 中的offline: enabled: !ENV [OFFLINE, false]正是读取该环境变量的开关。README 对此给出明确警告离线模式构建会禁用use_directory_urls配置从而保证用户能在本地文件系统中直接打开文档。发布或部署时不要启用该模式。也就是说OFFLINEtrue只适用于本地离线阅读或验证场景正式发布仍应使用默认URL 目录化构建方式。文档发布流程两步走与当前限制官方发布文档是一个两阶段流程site/README.md 的 “Release process” 一节发布新版本把当前/docs目录复制为docs分支上的新版本目录并在javadoc分支生成新的 Javadoc 构建make release ICEBERG_VERSION${ICEBERG_VERSION}构建并推送将生成的站点推到asf-site分支make deploy需要特别说明的是README 明确指出make release指令当前不可用项目团队仍在讨论是否以及如何自动化发布流程。理想方案是“对现有版本化文档快照合并独立的docs分支与javadoc分支随后用离线构建产物验证渲染正确性再由 release manager 合并 PR 完成发布”。因此在当前仓库状态下发布主要由人工执行版本快照 make deploy完成。链接校验monorepo 聚合的警告与 linkchecker 用法链接在构建中如何解析由于存在多个独立构建的 MkDocs 项目mkdocs-monorepo-plugin必须先构建各版本化文档站点再聚合顶层站点。这种“延迟聚合”会导致一个已知现象版本化文档在独立编译时会因无法引用项目外预期存在的文档而出现警告site/README.md 的 “Validate Links” 一节。根因是如果相对链接所需的目录层级与磁盘上的真实布局不一致就会产生这些错误。当前仓库中唯一出现该问题的地方是导航中指向 javadoc 的链接。构建后site_dir内部的链接结构示意如下./site/ ├── docs │ ├── docs │ │ ├── nightly │ │ │ ├── docs │ │ │ └── mkdocs.yml │ │ ├── latest │ │ │ ├── docs │ │ │ └── mkdocs.yml │ │ └── 1.4.0 │ │ ├── docs │ │ └── mkdocs.yml │ └── javadoc │ ├── nightly │ ├── latest │ └── 1.4.0 └── mkdocs.yml用 linkchecker 校验线上链接本地运行站点后可用linkchecker遍历页面链接输出 CSV 报告pip install linkchecker ./linkchecker http://localhost:8000 -r1 -Fcsv/link_warnings.csv cat ./link_warnings.csvREADME 同时指出了静态分析工具的局限mkdocs-linkcheck之类的工具只能校验单一 MkDocs 项目内的链接尚无法分析本工程这种“缝合的 monorepo”。一个尚未验证的改进方向是结合 offline 插件生成离线版本再对离线产物运行mkdocs-linkcheck比依赖在线站点更快、更不易出错而linkchecker仍可作为每日任务持续巡检线上链接问题。写给贡献者编写文档时的链接与路径规范site/README.md 末尾的 “Things to consider” 给出了所有文档贡献者必须遵守的四条铁律不要从文档内静态链接到公开的 Iceberg 站点例如https://iceberg.apache.org/docs/latest/branching。在本地环境修改了被链接页面时由于 URL 指向线上而非本地改动不会生效容易造成困惑只使用相对链接。引用站点根目录时用spec.md而非/spec.md静态站点应只引用docs/*但版本化文档可以正常引用静态内容如branching.md页面链接静态的spec.md避免静态链接到特定版本的文档nightly、latest、1.4.0等除非上下文确实与旧版本功能相关——这种情况几乎不应出现内部链接 Markdown 文件时始终使用.md后缀。这能告知 MkDocs 如何根据编译模式将链接编译为filename/index.html或filename.html两种模式下.md写法都能正常工作。在阅读本仓库文档时还需注意相对路径的基准site/README.md中形如dev/build.sh、Makefile的链接是相对于site/目录自身的映射到仓库根目录分别为 site/dev/build.sh 与 site/Makefile同理版本化文档内的链接如 docs/docs/spark-queries.md 引用的其他页面也以docs/docs/为基准。小结Apache Iceberg 的站点工程是一个典型的“多 MkDocs 项目 monorepo 聚合”实践site/承载非版本化页面与顶层构建配置docs/承载随版本演进的文档构建时通过 orphan 分支与 git worktree 临时挂载历史版本再由mkdocs-monorepo-plugin将全部子站点编织为单一站点。掌握make build / serve / clean / deploy四个命令即可完成从本地预览到上线发布的完整闭环在此基础上理解链接解析规则与OFFLINE离线模式就能安全、高效地参与 Iceberg 文档的编写与维护。赞分享数据湖湖仓一体大数据【免费下载链接】icebergApache Iceberg项目地址https://gitcode.com/gh_mirrors/iceberg5/iceberg点击查看免费下载相关推荐Apache Iceberg 官方站点与多版本文档工程化构建指南MkDocs Monorepo 插件Apache Iceberg 官方站点与多版本文档工程化构建指南MkDocs Monorepo 插件 本指南以 Iceberg 仓库根目录下的 site大数据数据湖OLAP数据存储Apache Iceberg 官方站点与版本化文档构建指南基于 MkDocs 与 git worktree 的完整实践Apache Iceberg 官方站点与版本化文档构建指南基于 MkDocs 与 git worktree 的完整实践 Apache Iceberg 仓库的数据湖大数据数据存储Mathesar 文档站构建与发布全解mkdocs-material、mike 多版本管理与 GitHub Pages 工作流Mathesar 文档站构建与发布全解mkdocs material、mike 多版本管理与 GitHub Pages 工作流 本文基于 Mathesar 仓数据库后端前端协作创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考