Docs

Requirements

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

Sphinx and Breathe 

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

(sudo) pip install sphinx sphinxconfig-bibtex breathe

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 and pdflatex are used to generate the companion PDF of the website.

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.

Note

For a full build of the C++ API documentation, you need to make doxygen to have it build its XML output which is consumed by Breathe before make html can be issued.

Website

The http://pdal.io website is regenerated from the *-maintenance branch using Github Actions. It will be committed by the PDAL-docs GitHub user and pushed to the https://github.com/PDAL/pdal.github.io repository. The website is then served via GitHub Pages.