Building the documentation

The ORCA documentation is composed of two parts. The user’s manual (what you are currently reading) and the API Reference. Since ORCA is written entirely in c++ the API documentation is generated with Doxygen. The manual, on the otherhand, is generated with python Sphinx… because frankly it is prettier.

Obviously, you can always visit the url: insert_url_here

to read the documentation online, but you can also generate it locally easily thanks to the magical powers of python.

How to build

First we need to install some dependencies for python and of course doxygen.

Python dependencies

pip3 install -U --user pip sphinx sphinx-autobuild recommonmark sphinx_rtd_theme

or if using Python 2.x

pip2 install -U --user pip sphinx sphinx-autobuild recommonmark sphinx_rtd_theme

Doxygen

You can always install Doxygen from source by following:

git clone https://github.com/doxygen/doxygen.git
cd doxygen
mkdir build
cd build
cmake -G "Unix Makefiles" ..
make
sudo make install

but we would recommend installing the binaries.

Linux:

sudo apt install doxygen

OSX:

brew install doxygen

Windows:

Download the executable file here: http://www.stack.nl/~dimitri/doxygen/download.html and follow the install wizard.

Building the docs with Sphinx

cd [orca_root]
cd docs/
make html

[orca_root] is the path to wherever you cloned the repo i.e. /home/$USER/orca/.

How to browse

Since Sphinx builds static websites you can simply find the file docs/build/html/index.html and open it in a browser.

If you prefer to be a fancy-pants then you can launch a local web server by navigating to docs/ and running:

make livehtml

This method has the advantage of automatically refreshing when you make changes to the .rst files. You can browse the site at: http://127.0.0.1:8000.