[pdal] API Documentation with Sphinx/Doxygen

[Howard Butler]

Michael,

I see you ported over the the doxygen stuff from libLAS, and I have it auto-building on pointcloud.org at http://pointcloud.org/doxygen

I also used breathe https://github.com/hobu/breathe to take doxygen's XML output and (grossly, at this time) map it into Sphinx http://pointcloud.org/cppapi.html  

The advantage of this approach is the output generation of all of our documentation can be through Sphinx.  We can control the documentation output for a nice, clean document http://michaeljones.github.com/breathe/directives.html 

Breathe can render restructured text that is embedded inside of header files using the \rst \endrst directives. This means that we can add Sphinx references inside of Doxygen API documentation back to other documents within our system.  I think this approach will provide a successful and beautiful documentation set for PDAL -- documentation that can exist in PDF, man, windows compiled help, and many others. It will allow us to present a unified interface to all of it as well. Pretty, well-linked docs mean people read them. We want people to read them :) 

If other people want to build this, they can crib off of the hourly script that keeps pointcloud.org running.  In short, you need the doxygen XML output before you run sphinx.  You'll need to install breath from my github fork as well using 'python setup.py install'

> #!/bin/bash
> cd /Data/www/pointcloud.org/git
> git pull
> cd /Data/www/pointcloud.org/git/doc
> make clean
> cd /Data/www/pointcloud.org/git/
> /usr/local/bin/doxygen doc/api/doxygen.conf
> chmod -R g+x,o+x /Data/www/pointcloud.org/git/doc/api
> export PATH=/usr/local/bin:$PATH
> cd /Data/www/pointcloud.org/git/doc
> make html
> cp -r -f  build/html/ /Data/www/pointcloud.org/htdocs
> cp /Data/www/pointcloud.org/git/doc/_static/logo/favicon.ico /Data/www/pointcloud.org/htdocs


Howard