1.. _development_docs:
2
3================================================================================
4Docs
5================================================================================
6
7
8Requirements
9================================================================================
10
11To build the PDAL documentation yourself, you need to install the following
12items:
13
14* Sphinx_
15* Breathe_
16* `Doxygen`_
17* `Latex`_
18* `dvipng`_
19
20.. _`dvipng`: https://en.wikipedia.org/wiki/Dvipng
21.. _`Latex`: https://en.wikipedia.org/wiki/LaTeX
22.. _`pdflatex`: https://www.tug.org/applications/pdftex/
23
24Sphinx_ and Breathe_
25--------------------------------------------------------------------------------
26
27Python dependencies should be installed from PyPI_ with ``pip`` or
28``easy_install``.
29
30.. code-block:: bash
31
32    (sudo) pip install sphinx sphinxconfig-bibtex breathe
33
34.. note::
35
36    If you are installing these packages to a system-wide directory, you may need
37    the **sudo** in front of the **pip**, though it might be better that instead
38    you use `virtual environments`_ instead of installing the packages system-wide.
39
40Doxygen
41--------------------------------------------------------------------------------
42
43The PDAL documentation also depends on `Doxygen`_, which can be installed from
44source or from binaries from the `doxygen website
45<http://www.stack.nl/~dimitri/doxygen/download.html>`_.  If you are on Max OS X
46and use `homebrew`_, you can install doxygen with a simple ``brew install
47doxygen``.
48
49Latex
50--------------------------------------------------------------------------------
51
52`Latex`_ and `pdflatex`_ are used to generate the companion PDF of the website.
53
54dvipng
55--------------------------------------------------------------------------------
56
57For math output, we depend on `dvipng`_ to turn `Latex`_ output into math PNGs.
58
59Generation
60================================================================================
61
62Once you have installed all the doc dependencies, you can then build the
63documentation itself.  The :file:`doc/` directory in the PDAL source tree
64contains a Makefile which can be used to build all documentation.  For a list
65of the output formats supported by Sphinx, simply type ``make``.  For example,
66to build html documentation:
67
68.. code-block:: bash
69
70    cd doc
71    make doxygen html
72
73The html docs will be placed in :file:`doc/build/html/`.  The ``make doxygen``
74is necessary to re-generate the API documentation from the source code using
75`Breathe`_ and `Sphinx`_.
76
77
78.. note::
79
80    For a full build of the :ref:`cppapi` documentation, you need to
81    ``make doxygen`` to have it build its XML output which is consumed
82    by `Breathe`_ before ``make html`` can be issued.
83
84
85Website
86================================================================================
87
88The http://pdal.io website is regenerated from the ``*-maintenance`` branch using
89Github Actions. It will be committed by the ``PDAL-docs`` `GitHub`_ user and pushed
90to the https://github.com/PDAL/pdal.github.io repository. The website
91is then served via `GitHub Pages`_.
92
93
94.. _`GitHub Pages`: https://pages.github.com/
95.. _`GitHub`: http://github.com/PDAL/PDAL
96.. _Sphinx: http://sphinx-doc.org/
97.. _Breathe: https://github.com/michaeljones/breathe
98.. _virtual environments: https://pypi.python.org/pypi/virtualenv
99.. _pypi: https://pypi.python.org/pypi
100.. _Doxygen: http://www.stack.nl/~dimitri/doxygen/
101.. _homebrew: http://mxcl.github.io/homebrew/
102