构建文档#

先决条件#

文档构建过程使用 Doxygen 和 Sphinx 以及一些扩展。

如果您使用 Conda，则可以通过一行代码安装所需的软件

conda install -c conda-forge --file=arrow/ci/conda_env_sphinx.txt

否则，您需要首先自行安装 Doxygen（例如，如果您使用 Linux，可以从您的发行版官方存储库安装）。然后，您可以使用以下命令安装基于 Python 的依赖项

pip install -r arrow/docs/requirements.txt

注意

如果您在 Windows 上构建文档，并非所有部分都可能正常构建。

这两个步骤是强制性的，必须按顺序执行。

注意

请注意，如果您的 pyarrow 构建不够全面，文档构建可能会失败。如果没有构建 CUDA 支持，Python API 文档的某些部分也无法构建。

完成这些步骤后，文档将以 HTML 格式呈现在 arrow/docs/_build/html 中。特别是，您可以将浏览器指向 arrow/docs/_build/html/index.html 以阅读文档并查看您所做的任何更改。

注意

如果您正在编写 Python 文档，并且在 macOS Monterey 上从源代码构建 pyarrow 时构建文档，则文档的 Python 部分可能不会包含在 _build/html 中。在这种情况下，请尝试在运行 make html 命令之前以非可编辑模式安装 pyarrow。

pushd arrow/docs
python -m pip install ../python --quiet
make html
popd

您可以使用 Archery 在 Docker 容器中构建文档。

archery docker run -v "${PWD}/docs:/build/docs" debian-docs

最终输出位于 ${PWD}/docs 目录下。

另请参阅

您可以在您正在处理的 GitHub 拉取请求中构建和预览文档。

为此，请在拉取请求中发布评论 @github-actions crossbow submit preview-docs。然后，渲染的文档将在 GitHub Actions 响应中提供，您需要单击 Crossbow 构建徽章

然后在工作流摘要中，您可以在页面底部找到文档预览摘要的链接

为了方便开发人员更新部分文档，可以只构建其中的一个子集。您可以构建

注意

只构建部分文档时，链接会断开！

因此，只构建文档的子集应仅用于初始工作，因为它使构建更快、更容易。

要检查文档的整体正确性，应该使用 make html 构建整个文档或使用 GitHub Actions。

您也可以实时构建文档（或其中的一部分）。这意味着保存的更改将自动触发文档重建。

pushd arrow/docs
make html-live

同样，可以使用 make format-live、make dev-live、make cpp-live 或 make python-live 自动构建部分文档。

您可以在单个目录中构建文档，而无需安装所有先决条件，方法是安装 sphinx，在要构建的目录中设置临时索引，然后构建该目录。

以下示例展示了如何在 arrow/docs/source/developers 目录中执行此操作。

安装 sphinx

pip install sphinx

导航到 arrow/docs 目录

cd arrow/docs

在目标目录中创建一个临时索引文件 temp_index.rst

echo $'.. toctree::\n\t:glob:\n\n\t*' > ./source/developers/temp_index.rst

在目标目录中构建文档

sphinx-build ./source/developers ./source/developers/_build -c ./source -D master_doc=temp_index

这会将目标目录中的所有内容构建到其内部一个名为 _build 的文件夹中，并使用 source 目录中的配置文件。

验证 HTML 文档后，您可以删除临时索引文件

rm ./source/developers/temp_index.rst