Building the Documentation#

Prerequisites#

The documentation build process usesDoxygen andSphinx along with a few extensions.

If you’re using Conda, the required software can be installed in a single line:

condainstall-cconda-forge--file=arrow/ci/conda_env_sphinx.txt

Otherwise, you’ll first need to installDoxygenyourself (for example from your distribution’s official repositories, ifusing Linux). Then you can install the Python-based requirements with thefollowing command:

pipinstall-rarrow/docs/requirements.txt

Building#

Note

If you are building the documentation on Windows, not all sectionsmay build properly.

These two steps are mandatory and must be executed in order.

  1. Process the C++ API using Doxygen

    pushdarrow/cpp/apidocdoxygenpopd

  2. Build the complete documentation using Sphinx.

    Note

    If you are working on the Python bindings documentation thenthis step requires thatpyarrow library is installedin your python environment. One way to accomplishthis is to follow the build instructions atPython Developmentand then runpythonsetup.pyinstall in arrow/python(it is best to do this in a dedicated conda/virtual environment).

    You can still build the documentation withoutpyarrowlibrary installed but note that Python part of the documentationwill be missing from the_build/html file structure and thelinks to the Python documentation will get broken.

    pushdarrow/docsmakehtmlpopd

Note

Note that building the documentation may fail if your build of pyarrow isnot sufficiently comprehensive. Portions of the Python API documentationwill also not build without CUDA support having been built.

After these steps are completed, the documentation is rendered in HTMLformat inarrow/docs/_build/html. In particular, you can point your browseratarrow/docs/_build/html/index.html to read the docs and review any changesyou made.

Note

If you are working on the Python documentation and are building the documentationwithpyarrow build from source on macOS Monterey, the Python section of thedocumentation might not be included in the_build/html. In this case, tryinstallingpyarrow in non-editable mode first before running themakehtmlcommand.

pushdarrow/docspython-mpipinstall../python--quietmakehtmlpopd

Building with Docker#

You can useArchery to build the documentation within aDocker container.

archerydockerrun-v"${PWD}/docs:/build/docs"debian-docs

The final output is located under the${PWD}/docs directory.

Building a docs preview in a Pull Request#

You can build and preview the documentation within a GitHub pull request you are working on.

To do so, post the comment@github-actionscrossbowsubmitpreview-docsto the pull request. The rendered documentation will then be available within theGitHub Actions response, where you need to click on the Crossbow build badge:

GitHub Actions response with the crossbow build status.

Crossbow build status#

and then in the summary of the workflow you can find the link to the Docs Previewsummary at the bottom of the page:

Crossbow workflow page with the Docs Preview summary section.

Docs Preview summary section#

Building for dev purposes#

Building subsections#

To make it easier for developers to update parts of the documentation, one canbuild only a subset of it. You can build:

  • Specifications and protocol section (docs/source/format) with:

    pushdarrow/docsmakeformatpopd

    Rendered HTML format can be found inarrow/docs/_build/html/format.

  • Development section (docs/source/developers) with:

    pushdarrow/docsmakedevpopd

    Rendered HTML format can be found inarrow/docs/_build/html/developers.

  • C++ section (docs/source/cpp) with:

    pushdarrow/docsmakecpppopd

    Rendered HTML format can be found inarrow/docs/_build/html/cpp.

  • Python section (docs/source/python) with:

    pushdarrow/docsmakepythonpopd

    Rendered HTML format can be found inarrow/docs/_build/html/python.

Note

When building only a part of the documentation the links will get broken!

For this reason building only a subset of the documentation should only beused in the initial work as it makes the building faster and easier.

To check for the correctness of the documentation overall one shouldbuild the whole documentation withmakehtml or useGitHub Actions.

Building live#

You can also build the documentation (or a part of it) live. This means thechanges saved will automatically trigger the documentation to be rebuilt.

pushdarrow/docsmakehtml-live

The same way one could usemakeformat-live,makedev-live,makecpp-liveormakepython-live to auto-build part of the documentation.

Building a single directory for dev purposes without all the pre-requisites#

You can build documentation in a single directory without needing to installall of the pre-requisites by installing sphinx, setting up a temporaryindex in the directory you want to build and then building that directory.

The example below shows how to do this in thearrow/docs/source/developers directory.

Installsphinx:

pipinstallsphinx

Navigate to thearrow/docs directory:

cdarrow/docs

Create an temporary index filetemp_index.rst file in the target directory:

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

Build the docs in the target directory:

sphinx-build./source/developers./source/developers/_build-c./source-Dmaster_doc=temp_index

This builds everything in the target directory to a folder inside of itcalled_build using the config file in thesource directory.

Once you have verified the HTML documents, you can remove temporary index file:

rm./source/developers/temp_index.rst