建置文件#

先決條件#

文件建置流程使用 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 中。在這種情況下，請嘗試先以非可編輯模式安裝 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 建置.

在 Pull Request 中建置文件預覽#

您可以在您正在處理的 GitHub Pull Request 中建置並預覽文件。

若要執行此操作，請在 Pull Request 中發布註解 @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