Apache Arrow 文档构建完全指南：从 Doxygen、Sphinx 到 PR 预览与 Docker 流水线

数据工程数据分析大数据【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址https://gitcode.com/gh_mirrors/arrow12/arrow点击查看免费下载本篇技术指南围绕 Apache Arrow 官方文档的构建体系展开完整讲解如何在本仓库含 C、Python、Java、R 等多语言文档源中从零搭建文档构建环境、执行标准的两步构建流程Doxygen → Sphinx、利用docs/Makefile提供的分节与实时构建目标、通过 Archery Docker 在容器内构建以及如何在 Pull Request 中触发 CI 自动生成文档预览。读完本文你将掌握在本地复现docs/_build/html完整 HTML 文档、按需只编译format/dev/cpp/python子集、以及在贡献文档时验证链接与内容正确性的全套实操方法。文档体系与构建工具链概览Apache Arrow 的文档源文件位于仓库的 docs/source 目录下按内容主题划分为format列式内存格式与协议规范、developers开发者指南、cpp、python、java等子目录。文档构建依赖两套工具协同工作Doxygen负责处理 C 源码中的注释生成 C API 参考配置见 cpp/apidoc/Doxyfile其PROJECT_NAME为Apache Arrow (C)OUTPUT_DIRECTORY可通过环境变量覆盖。Sphinx负责将各语言文档的 reStructuredText.rst与 MyST Markdown 源文件组装为最终站点。构建配置位于 docs/source/conf.py其中声明了breathe嵌入 Doxygen 产物、numpydoc、myst_parser、sphinx_design、sphinx_copybutton、sphinxcontrib_mermaid等扩展。Sphinx 构建驱动 是日常构建的核心入口它封装了以下常用目标Make 目标构建内容输出目录相对docs/make html完整文档_build/htmlmake dev仅开发者文档source/developers_build/html/developersmake format仅格式与协议规范source/format_build/html/formatmake cpp仅 C 文档source/cpp_build/html/cppmake python仅 Python 文档source/python_build/html/pythonmake html-live/dev-live/format-live/cpp-live/python-live实时自动重建对应部分同对应静态目标make java_tutorial/java_dev仅 Java 教程 / Java 开发文档_build/html/tutorial/java/_build/html/developers/javamake linkcheck/doctest/coverage链接完整性 / doctest / 覆盖率检查_build/linkcheck等默认的SPHINXOPTS -j8docs/Makefile表示以 8 进程并行构建以加速如需将警告视为错误可手动追加-W该选项在 Makefile 中被注释保留。环境准备一键安装全部构建依赖构建文档需要 Doxygen 与 Sphinx 及若干扩展。官方文档docs/source/developers/documentation.rst提供了两种安装途径。方式一Conda推荐单条命令完成使用 Conda 时依赖清单集中维护在 ci/conda_env_sphinx.txtconda install -c conda-forge --filearrow/ci/conda_env_sphinx.txt该清单涵盖了 Doxygen、Sphinx锁定sphinx6.2、breathe、numpydoc、myst-parser、pydata-sphinx-theme0.14、sphinx-autobuild、sphinx-design、sphinx-copybutton、sphinx-lint、sphinxcontrib-jquery、sphinxcontrib-mermaid、pandas以及用于 doctest 的pytest-cython0.2.2固定版本以规避上游 issue。方式二Doxygen pip若不使用 Conda需先从操作系统官方软件源自行安装 Doxygen例如 Linux 发行版的包管理器再通过 pip 安装 Python 依赖pip install -r arrow/docs/requirements.txtrequirements.txt 头部明确标注“请与conda_env_sphinx.txt保持同步”因此两种途径安装的依赖版本一致。注意 pip 版本用pydata-sphinx-theme~0.14、myst-parser[linkify]表示范围/附加依赖与 Conda 清单中的固定写法略有差异但含义等价。完整构建必须按顺序执行的两个步骤完整构建分两步且必须按顺序执行原文档明确强调“mandatory and must be executed in order”。第一步用 Doxygen 处理 C APIpushd arrow/cpp/apidoc doxygen popd此步骤读取 cpp/apidoc/Doxyfile 中的配置扫描 C 源码生成 XML 格式的 API 文档中间产物供 Sphinx 的breathe扩展后续嵌入。若需要调整产物输出位置可以通过OUTPUT_DIRECTORY变量覆盖。第二步用 Sphinx 构建完整文档pushd arrow/docs make html popd构建完成后完整 HTML 站点位于arrow/docs/_build/html以仓库根目录为基准即docs/_build/html直接用浏览器打开arrow/docs/_build/html/index.html即可阅读文档并检查自己所做的修改。Python 绑定文档的特殊前置条件构建 Python 绑定pyarrow文档时要求当前 Python 环境中已安装pyarrow库。官方推荐先按照 Python 开发环境指南 完成源码构建再在专用 conda/virtualenv 环境中执行python setup.py install在arrow/python目录下。需要说明的是本仓库为只读快照此处仅为文档构建环境配置介绍不涉及仓库变更。在未安装pyarrow的情况下依然可以构建文档但 docs/source/conf.py 中的逻辑会走except (ImportError, LookupError)分支将exclude_patterns设为[python]即 Python 部分文档不会出现在_build/html中且指向 Python 文档的链接会失效。类似的conf.py还会探测pyarrow.cuda、pyarrow.flight、pyarrow.orc、pyarrow.parquet.encryption等可选子模块的可用性cuda_enabled、flight_enabled等标志通过ifconfig指令条件化包含对应 API 文档。因此若本地pyarrow构建不够完整文档构建可能失败未编译 CUDA 支持时Python API 文档的 CUDA 部分也无法生成。macOS Monterey 的已知问题在 macOS Monterey 上以源码构建的pyarrow构建文档时Python 部分可能不会出现在_build/html中。官方给出的解决方法是先以非 editable 模式安装pyarrow再执行make htmlpushd arrow/docs python -m pip install ../python --quiet make html popdWindows 平台提示原文档提醒在 Windows 上构建时并非所有章节都能正常构建。使用 Archery 与 Docker 构建Apache Arrow 提供了 Archery 开发工具位于 dev/archery可通过 Docker 容器一键构建文档无需在宿主机配置任何文档依赖archery docker run -v ${PWD}/docs:/build/docs ubuntu-docs其中ubuntu-docs是预置了完整文档构建环境的 Docker 镜像CI 中对应的 Dockerfile 见 ci/docker/linux-apt-docs.dockerfile-v将当前仓库的docs目录挂载进容器最终构建产物直接落回宿主机的${PWD}/docs目录下。更多容器构建细节可参考 持续集成文档 中的 Docker 构建章节。在 Pull Request 中生成文档预览为方便在提交文档改动时快速核对渲染效果官方提供了 CI 驱动的文档预览机制任务定义见 dev/tasks/tasks.yml 中的preview-docs任务在目标 Pull Request 下留言github-actions crossbow submit preview-docs渲染好的文档会出现在 GitHub Actions 的响应中点击 Crossbow 构建徽章即可进入构建详情页在工作流摘要页底部的 Docs Preview summary 区块中可以找到预览链接该机制尤其适合验证改动后全文链接是否完整、格式是否正确的场景。面向开发者的高效构建技巧只构建部分章节当只需更新某一子模块文档时可以只构建对应子集以节省时间仅构建格式与协议规范docs/source/formatmake format输出在docs/_build/html/format仅构建开发者文档docs/source/developersmake dev输出在docs/_build/html/developers仅构建 C 文档docs/source/cppmake cpp输出在docs/_build/html/cpp仅构建 Python 文档docs/source/pythonmake python输出在docs/_build/html/python。注意部分构建时文档中的交叉链接会失效因为被引用章节未被生成因此它只适合开发初期的快速迭代最终必须用make html或 PR 预览验证整体正确性。实时live构建使用sphinx-autobuild依赖已在环境清单中可实现保存即自动重建pushd arrow/docs make html-live同理make format-live、make dev-live、make cpp-live、make python-live可实时自动重建对应子集。其中python-live目标还通过--ignore排除了自动生成目录source/python/generated/*.rst避免生成文件触发无限重建循环docs/Makefile。免装全部前置依赖的“单目录快速构建”如果只想预览某个目录例如docs/source/developers而不安装所有前置依赖官方给出了一个轻量技巧pip install sphinx cd arrow/docs echo $.. toctree::\n\t:glob:\n\n\t* ./source/developers/temp_index.rst sphinx-build ./source/developers ./source/developers/_build -c ./source -D master_doctemp_index原理说明用echo在该目录生成一个临时索引temp_index.rst其中的toctree使用:glob:通配包含同目录全部文档sphinx-build以-c ./source复用根目录的 docs/source/conf.py 配置并通过-D master_doctemp_index将临时索引设为主文档产物输出到该目录下的_build文件夹。验证完毕后记得删除临时文件rm ./source/developers/temp_index.rst注意docs/Makefile的clean与clean-*目标同样会清理_build与自动生成文件可用于恢复干净的构建状态。构建质量自检清单结合原文档的注意事项与仓库配置构建文档后可按下表自查检查项判定标准完整构建产物docs/_build/html/index.html可正常打开Python 章节环境已安装pyarrow含 CUDA 等可选模块_build/html包含python子目录且无失效链接部分构建仅用于开发中间态提交前必须用make html验证全文链接完整性可运行make linkcheck检查外部链接部分构建必然产生失效交叉链接Windows 平台注意并非所有章节都能正常构建PR 预览提交改动后留言github-actions crossbow submit preview-docs触发 CI 渲染相关文档导航本文依据的原始文档docs/source/developers/documentation.rst构建驱动与全部目标docs/Makefile构建配置扩展、条件包含逻辑docs/source/conf.pyConda 依赖清单 / pip 依赖清单ci/conda_env_sphinx.txt / docs/requirements.txtDoxygen 配置cpp/apidoc/DoxyfilePython 开发环境构建 pyarrow 前置条件docs/source/developers/python.rst开发者文档总入口docs/source/developers/index.rst赞分享数据工程数据分析大数据【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址https://gitcode.com/gh_mirrors/arrow12/arrow点击查看免费下载相关推荐Apache Arrow 文档构建完全指南Doxygen Sphinx 双引擎流水线与 PR 文档预览Apache Arrow 文档构建完全指南Doxygen Sphinx 双引擎流水线与 PR 文档预览 本文是 Apache Arrow 仓库开发者文档大数据数据分析数据工程序列化Noto Emoji 完整指南5 分钟装好字体让表情符号乱码一次清零Noto Emoji 完整指南5 分钟装好字体让表情符号乱码一次清零 手机选的表情一贴到电脑上就变成一排灰白小方块这是缺了字形而 Noto Emo数据工程大数据序列化数据分析Apache Arrow 文档贡献与本地构建实战从 Edit this page 到 Doxygen Sphinx 全量构建Apache Arrow 文档贡献与本地构建实战从 Edit this page 到 Doxygen Sphinx 全量构建 本文基于 Apache Ar数据工程数据分析大数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考