.. _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