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 ACloudViewer repo and run doxygen.

git clone https://github.com/Asher-1/ACloudViewer
cd ACloudViewer/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 ACloudViewer#

Note

Current version: 3.9.4

Download from the Releases page.

Install from pip (CUDA version):

wget https://github.com/Asher-1/ACloudViewer/releases/download/v3.9.4/cloudviewer-3.9.4-cp313-cp313-manylinux_2_35_x86_64.whl
pip install cloudviewer-3.9.4-cp313-cp313-manylinux_2_35_x86_64.whl

Or install the CPU-only version:

wget https://github.com/Asher-1/ACloudViewer/releases/download/v3.9.4/cloudviewer_cpu-3.9.4-cp313-cp313-manylinux_2_35_x86_64.whl
pip install cloudviewer_cpu-3.9.4-cp313-cp313-manylinux_2_35_x86_64.whl

Tip

Replace 3.9.4 with the desired version, and cp313 with your Python version (cp310 for 3.10, cp311 for 3.11, cp312 for 3.12, cp313 for 3.13).

To instead build ACloudViewer from source, see build_from_source.

Install Python dependencies#

pip install -r docs/requirements.txt

Build docs#

cd docs

# Run sphinx-build to generate documentation
# For HTML documentation
make html

# For PDF documentation
make latexpdf

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

Alternative build with make_docs.py (if available):

cd docs

# Run `python make_docs.py --help` to see 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

Preview#

Open docs/_build/html/index.html (or docs/_out/html/index.html if using make_docs.py) in a web browser to preview the docs.

# Linux
xdg-open docs/_build/html/index.html

# macOS
open docs/_build/html/index.html

# Or use any browser
google-chrome docs/_build/html/index.html
firefox docs/_build/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 ACloudViewer. These can be created with the pybind11-stubgen tool and placed alongside the cloudViewer files:

# Install cloudViewer and pybind11-stubgen
pip install pybind11-stubgen cloudViewer

# Print location of installed cloudViewer library
pip show cloudViewer
# This outputs a line like:
# Location: path/to/venv/site-packages

# Create stubs and place them next to cloudViewer files
pybind11-stubgen -o <path/to/venv/site-packages/> --root-suffix "" cloudViewer

Troubleshooting#

Issue: Sphinx build fails with import errors

Solution: Make sure ACloudViewer is properly installed in your Python environment:

python -c "import cloudViewer as cv3d; print(cv3d.__version__)"

Issue: Doxygen not found

Solution: Install doxygen using your system package manager as described above.

Issue: LaTeX errors when building PDF

Solution: Ensure you have a complete TeX distribution installed. On Ubuntu, install texlive-full for all packages:

sudo apt-get install texlive-full

Issue: Notebooks fail to execute

Solution: If running on a headless server, make sure to configure headless rendering or skip notebook execution with --execute_notebooks=never flag.

Contributing to Documentation#

We welcome contributions to improve the documentation! Please see our ../CONTRIBUTING guide for more information.

When writing documentation:

  1. Follow the existing style and structure

  2. Use reStructuredText syntax

  3. Add code examples where appropriate

  4. Build and preview locally before submitting

  5. Check for spelling and grammar errors

For more details, visit the ACloudViewer GitHub repository.