Docs

Requirements

To build the PDAL documentation yourself, you need to install the following items:

Sphinx, Breathe and Bootstrap

Python dependencies should be installed from PyPI with pip or easy_install.

(sudo) pip install sphinx breathe rst2pdf sphinx_bootstrap_theme

Note

If you are installing these packages to a system-wide directory, you may need the sudo in front of the pip, though it might be better that instead you use virtual environments instead of installing the packages system-wide.

Doxygen

The PDAL documentation also depends on Doxygen, which can be installed from source or from binaries from the doxygen website. If you are on Max OS X and use homebrew, you can install doxygen with a simple brew install doxygen.

Latex

Latex is used for equation editing inside of Sphinx. It is used to generate figures and graphs.

dvipng

For math output, we depend on dvipng to turn Latex output into math PNGs.

Generation

Once you have installed all the doc dependencies, you can then build the documentation itself. The doc/ directory in the PDAL source tree contains a Makefile which can be used to build all documentation. For a list of the output formats supported by Sphinx, simply type make. For example, to build html documentation:

cd doc
make doxygen html

The html docs will be placed in doc/build/html/. The make doxygen is necessary to re-generate the API documentation from the source code using Breathe and Sphinx.

Website

The http://pdal.io website is regenerated from the master branch at the following cron schedule:

30 2,8,12,16,20 * * * /home/pdal/periodic/pdal.sh

It is generated by a Digital Ocean droplet that uses the PDAL-docs GitHub user to write to the https://github.com/PDAL/pdal.github.io repository. The website is then served via GitHub Pages.