Docs¶
Requirements¶
To build the PDAL documentation yourself, you need to install the following items:
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
.
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 *-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