构建文档#

先决条件#

文档构建过程使用 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 上构建文档，则可能并非所有部分都能正确构建。

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

使用 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 中。在这种情况下，请尝试在运行 make html 命令之前，先以非可编辑模式安装 pyarrow。

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