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.

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 brewinstalldoxygen.

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 makedoxygen
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
makedoxygen to have it build its XML output which is consumed
by Breathe before makehtml can be issued.

A Install Docker image, pdal/docs contains the full compliment of requirements,
and it is used by PDAL’s Travis continuous integration to build and commit
new versions of the website. You can easily build the docs using Docker by
issuing the following command:

dockerrun-v/path/to/pdal/root/tree:/data-w/data/docpdal/docsmakehtml

The pdal/docs container can be refreshed on DockerHub by tagging a docbuild
tag and force-pushing it to the main repository:

$ git tag -f docbuild
$ git push origin -f refs/tags/docbuild

Note

The pdal/docs container is constructed from the Dockerfile at whatever revision the docbuild tag points to.