构建文档#

前提条件#

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

如果您使用的是 Conda，则只需一行代码即可安装所需的软件

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

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

pip install -r arrow/docs/requirements.txt

构建#

注意

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

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

使用 Doxygen 处理 C++ API
```
pushd arrow/cpp/apidoc
doxygen
popd
```
使用 Sphinx 构建完整的文档。

注意

如果您正在处理 Python 绑定文档，则此步骤要求在您的 python 环境中安装 pyarrow 库。一种方法是按照 Python 开发中的构建说明进行操作，然后在 arrow/python 中运行 python setup.py install（最好在专用的 conda/虚拟环境中执行此操作）。

您仍然可以在未安装 pyarrow 库的情况下构建文档，但请注意，文档的 Python 部分将从 _build/html 文件结构中丢失，并且指向 Python 文档的链接将断开。
```
pushd arrow/docs
make html
popd
```

注意

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

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

注意

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

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

使用 Docker 构建#

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

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

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

另请参阅

运行 Docker 构建.

在拉取请求中构建文档预览#

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

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

GitHub Actions response with the crossbow build status. — Crossbow 构建状态#

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

Crossbow workflow page with the Docs Preview summary section. — 文档预览摘要部分#

为开发目的构建#

构建子章节#

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

使用以下命令构建规范和协议部分（docs/source/format）
```
pushd arrow/docs
make format
popd
```
渲染的 HTML 格式可以在 arrow/docs/_build/html/format 中找到。
使用以下命令构建开发部分（docs/source/developers）
```
pushd arrow/docs
make dev
popd
```
渲染的 HTML 格式可以在 arrow/docs/_build/html/developers 中找到。
使用以下命令构建 C++ 部分（docs/source/cpp）
```
pushd arrow/docs
make cpp
popd
```
渲染的 HTML 格式可以在 arrow/docs/_build/html/cpp 中找到。
使用以下命令构建 Python 部分（docs/source/python）
```
pushd arrow/docs
make python
popd
```
渲染的 HTML 格式可以在 arrow/docs/_build/html/python 中找到。

注意

仅构建文档的一部分时，链接将断开！

因此，仅构建文档的子集应该仅在初始工作中使用，因为它可以使构建更快更容易。

要检查整个文档的正确性，应该使用 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

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

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

rm ./source/developers/temp_index.rst