# Docs

## Requirements

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

- Sphinx
- Breathe
- Doxygen
- Latex
- dvipng

Note

For the website, PDAL builds the documentation using Travis and Install Docker. You can get a listing of the exact Ubuntu requirements in the Dockerfile. See Continuous Integration for more detail.

### 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 Travis. 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.

Note

The website is regenerated and pushed only on the `after_success` Travis call. If the tests aren’t passing, the website won’t be updated.

## Building With Docker

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:

    docker run -v /path/to/pdal/root/tree:/data -w /data/doc pdal/docs make html

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.