.. _development_docs:

================================================================================
Docs
================================================================================


Requirements
================================================================================

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

* Sphinx_
* Breathe_
* `sphinx_bootstrap_theme`_
* `Doxygen`_
* `Latex`_
* `dvipng`_

.. _`dvipng`: https://en.wikipedia.org/wiki/Dvipng
.. _`sphinx_bootstrap_theme`: https://pypi.python.org/pypi/sphinx-bootstrap-theme/
.. _`Latex`: https://en.wikipedia.org/wiki/LaTeX

Sphinx, Breathe_ and Bootstrap
--------------------------------------------------------------------------------

Python dependencies should be installed from PyPI_ with ``pip`` or
``easy_install``.

.. code-block:: bash

    (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
<http://www.stack.nl/~dimitri/doxygen/download.html>`_.  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 :file:`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:

.. code-block:: bash

    cd doc
    make doxygen html

The html docs will be placed in :file:`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`_.

.. _`GitHub Pages`: https://pages.github.com/
.. _`GitHub`: http://github.com/PDAL/PDAL

.. _`Digital Ocean`: digitalocean.com

.. _Sphinx: http://sphinx-doc.org/
.. _Breathe: https://github.com/michaeljones/breathe
.. _virtual environments: https://pypi.python.org/pypi/virtualenv
.. _pypi: https://pypi.python.org/pypi
.. _Doxygen: http://www.stack.nl/~dimitri/doxygen/
.. _homebrew: http://mxcl.github.io/homebrew/
