OpenRAVE Documentation

Documentation System


Describes the OpenRAVE documentation system and all necessary function calls for generating and maintaining the documents. This is mean for developers.


apt-get remove python-sphinx
apt-get install python-pygments python-setuptools python-lxml python-matplotlib dvipng dia-common python-svn
easy_install --upgrade docutils
easy_install sphinx

doxygen version 1.7.1 or later is required.

breathe is used for converting doxygen to python comments so that python users can be internal help for the C++ bindings. The breathe sources are in docs/breathe.

If using latex, install:

apt-get install  dot2tex texlive-base texlive-latex-base texlive-pictures texlive-fonts-recommended

For japanese fonts install:

apt-get install latex-cjk-japanese

Getting Started

OpenRAVE uses:

  • doxygen for the core system and c++ documentation
  • reStructuredText for all other documentation.

The following script generates all documentation for English and Japanese:

cd docs

Upload the generated documentation to the server with:

cd docs

Most build files are stored in the docs/build directory. All images are saved into docs/images, including automatically generated ones.

Because running can take a long time, developers should execute the individual commands pertaining to the part of the system they are maintaining. The commands are given in the following sections.

Python (reStructuredText)

Compiling the python documentation is divided into several steps.

# Take in the doxygen comments from the C++ API and creates python/bindings/docstrings.cpp, which is then compiled in the openravepy_int module.

# Generate rst files from all the openravepy modules using sphinx-autopackage-script/

# Generate rst files from the interfaces documentation and testing results.

# Compile with sphinx-build

The entire script is:

# argument $1 is language: en, ja
# build the python documentation and openrave homepage
if [ "$1" == "ja" ]; then
    export LANG=ja_JP.UTF-8
    export LANG=en_US.UTF-8
rm -rf _templates/examples.html _templates/databases.html _templates/database_generator_template.rst $1/openravepy build/$1/main
python --outdir=$1
if [ "$?" -ne 0 ]; then echo " failed"; exit 1; fi 
mkdir -p $1/openravepy
ln -s -f `openrave-config --python-dir`/openravepy/_openravepy_ openravepy
python sphinx-autopackage-script/ --dest-dir=$1/openravepy --suffix=rst --maxdepth=3 --no-toc --sep-files `pwd`/openravepy
rm openravepy
if [ "$?" -ne 0 ]; then echo " failed"; exit 1; fi 
python --lang=$1 --ikfaststats=ikfaststats.pp
if [ "$?" -ne 0 ]; then echo " failed"; fi 
ln -s -f `openrave-config --python-dir`/openravepy/_openravepy_ openravepy
sphinx-build -b html -c . $1 build/$1/main
rm openravepy
if [ "$?" -ne 0 ]; then echo "sphinx-build failed"; exit 1; fi 

Because the documentation for openravepy is built from the install directory, whenever a change to the openravepy documentation made openrave has to be reinstalled with make install.

C++ Core Documentation (doxygen)

Compiling HTML and Latex:

cd docs
python --lang=en
firefox build/en/coreapihtml/index.html
evince build/en/coreapilatex/refman.pdf

The script internally makes these calls:

cd docs
doxygen build/Doxyfile.html.en
doxygen build/Doxyfile.latex.en

The build/Doxyfile.html.en file is generated from Doxyfile.html and Doxyfile.en. The separation is necessary in order to provide better localization support for multiple languages.

The mainpage and bulk of the documentation is in docs/mainpage.dox. Installation instructions are in docs/install.dox.

Use the en, ja, ~ tags to switch between language modes.

To reference image in docs/images/tutorial0_myimage.png, write:

\image html tutorial0_myimage.png
\image latex tutorial0_myimage.png "My Caption" width=15cm


To build the webpage of interface descriptions, run


This outputs a set of reStructuredText files, which can be used by sphinx to build up the page.

Robots Database

Generate a set of webpages for each robot using the statistics file output from test/

An image of all the robots in openrave can be extracted using the script:

cd docs
python --outdir="en/ikfast" --ikfaststats=ikfaststats.pp


Having problems with OpenRAVE?