Build documentation#

The main documentation and Python documentation is written in reStructuredText and generated by sphinx. The C++ API documentation is generated by Doxygen.

Documentation can be built on Ubuntu or macOS. Building documentation on Windows may also be possible but is not officially tested.

If you’re building documentation on a computer without a display, please use Headless rendering, otherwise the Jupyter tutorials will fail to execute.

Install system dependencies#

Ubuntu

sudo apt-get -y install doxygen texlive texlive-latex-extra ghostscript pandoc

macOS

First, install a TeX distribution such as MacTeX.

brew install ghostscript pandoc doxygen

Building C++ documentation#

If you only want to build C++ API documentation, clone the Open3D repo and run doxygen.

git clone https://github.com/isl-org/open3d
cd open3d/docs
doxygen Doxyfile.in

Start browsing the generated C++ API documentation from the file docs/doxygen/html/index.html. Read on if you want to build the full documentation (including Python API and tutorials).

Install or Build Open3D#

pip install open3d

To instead build Open3D from source, see Build from source.

Install Python dependencies#

pip install -r docs/requirements.txt

Build docs#

cd docs

# Run `python make_docs.py --help` to usage of the flags.
python make_docs.py --help

# Example: build .rst and C++ docs only, skip notebooks.
python make_docs.py --execute_notebooks=never --sphinx --doxygen

# Example: build .rst and C++ docs only, skip notebooks, with parallel build.
python make_docs.py --execute_notebooks=never --sphinx --doxygen --parallel

# Example: build .rst and c++ docs, execute notebooks when it has not been executed.
python make_docs.py --execute_notebooks=auto --sphinx --doxygen

The docs html will be saved in docs/_out folder.

Preview#

Open docs/_out/html/index.html in a web browser to preview the docs.

google-chrome docs/_out/html/index.html

Create Python stubs (type hints) for type checking and autocomplete#

You can get type checking and auto-complete features in editors and IDES (e.g.: VS Code, PyCharm, etc.) using type hints produced from Open3D. These can be created with the pybind11-stubgen tool and placed alongside the Open3D files:

# Install open3d and pybind11-stubgen
pip install pybind11-stubgen open3d
# Print location of install open3d library
pip show open3d
# This outputs a line like:
# Location: path/to/venv/site-packages
# Create stubs and place them next to Open3D files
pybind11-stubgen -o <path/to/venv/site-packages/> --root-suffix "" open3d