Compiling the documentation

The documentation is written using doxygen for c++, sphinx for python, and breathe to tie them together. It yields this

Pre-requisites

Installing doxygen

• Linux: apt-get, yum, or other package manager
• Mac: brew install doxygen
• Windows: binaries can be found here

Installing Sphinx

• Linux: apt-get, yum, or pip (same as Mac)
• Mac: pip install sphinx
• Windows: Depending on your setup
  • conda.bat install sphinx
  • or, pip install sphinx

WARNING: If using a virtual environment, it is recommended to run pip install --upgrade sphinx (within the virtual environment) so that sphinx is set up with the right path. Then one should make sure that SPHINX_EXECUTABLE in `build/CMakeCache.txt`` points to the correct sphinx executable.

Installing Breathe

In all cases, do pip install Breathe, or easy_install Breathe. On windows, it might first be necessary to install the pip package via conda.

Installing Sphinx plugin for citation

sphinxcontrib.bibtext makes it possible to use a bibtex file, documentation/source/bibliography.bib, to hold reference to papers. It can be installed with pip install sphinxcontrib-bibtex

NOTE: On Mac, with python2.7 installed from brew, I've had to add an empty __init__.py file in site-packages/sphinxcontrib for its bibtex subpackage to be found.

Compiling the Documentation for Python

The code must be installed and accessible before trying to compile the documentation, at least when the python bindings are compiled. This means:

1. The library is in the PATH (windows), DYLD_LIBRARY_PATH (Mac), or the LD_LIBRARY_PATH (Linux)
2. The python bindings are in the PYTHONPATH (e.g. python -c "import dcprogs.likelihood" does not fail)

The reason for this is that python documentation software will interrogate the package to find out what it contains. Hence the package needs to be available and loadable. Please refer to the wiki for instructions on installing DCProgs.

Once DCProgs is installed and available, do:

> cd /path/to/buid/
> make documentation

The documentation should be available at path/to/build/documentation/sphinx/index.html.

Updating the web-page

The dat for the web page resides on the same git repository that the code does in a special branch called gh-pages. And conversely, github knows to render here anything that is in the branch gh-pages.

It is possible to update the data and the web-page with the following commands:

1. Commit any changes to the code that should be kept safe.

2. Go to the build directory

3. Update the docs

   > make documentation 

4. Checkout the gh_pages using one the two lines below:

   > git checkout -t origin/gh-pages # If first time, if the branch does not exist 
   > git checkout gh-pages 
   

   At this point, the source directory does not contain code anymore. It contains data for the documentation webpage.

5. Copy the new documentation from the build directory to the source directory:

   > rsync -r documentation/sphinx/* ..

6. Commit the changes to the documentation. If nothing happens, there were likely no changes:

   > git commit -a

   At this juncture, the data has been updated on the local computer. All that needs to be done is to push it to github, so github knows to render it.

7. Push the changes back to github so the web-site can be updated:

   > git push

8. Checkout the master branch again

   > git checkout master

Compiling the documentation without Python bindings

A fairly bare documentation of the c++ api is available. It can be obtained by running

> cd /path/to/build/
> make doxydocs

The documents are then available at build/documentation/html/index.html.