.. _builddocs:

Build documentation

The main documentation and Python documentation is written in reStructuredText <http://www.sphinx-doc.org/en/stable/rest.html>_ and generated by sphinx <http://www.sphinx-doc.org/>. The C++ API documentation is generated by Doxygen <http://www.doxygen.nl/>.

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 :ref:headless_rendering, otherwise the Jupyter tutorials will fail to execute.

Install system dependencies

Ubuntu

.. code-block:: bash

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

macOS

First, install a TeX distribution such as MacTeX <http://www.tug.org/mactex/>_.

.. code-block:: bash

brew install ghostscript pandoc doxygen

Building C++ documentation

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

.. code-block:: bash

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

.. code-block:: bash

pip install open3d

To instead build Open3D from source, see :ref:compilation.

Install Python dependencies

.. code-block:: bash

pip install -r docs/requirements.txt

Build docs

.. code-block:: bash

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.

.. code-block:: bash

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:

.. code-block:: bash

# 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