构建文档#

先决条件#

文档构建过程使用 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 绑定文档，那么此步骤需要 pyarrow 库已安装在您的 python 环境中。实现此目的的一种方法是按照 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" debian-docs

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

另请参阅

运行 Docker 构建.

在 Pull Request 中构建文档预览#

您可以在您正在处理的 GitHub pull request 中构建和预览文档。

为此，请将注释 @github-actions crossbow submit preview-docs 发布到 pull request。然后，渲染的文档将在 GitHub Actions 响应中可用，您需要在其中单击 Crossbow 构建徽章

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

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

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

为了开发目的而构建#

构建子章节#

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

规范和协议部分 (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

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

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

rm ./source/developers/temp_index.rst