==========================
Building the documentation
==========================

Due to the limitations of Python :py:mod:`distutils` and :py:mod:`setuptools`
not all of the documentation can be build from within :file:`setup.py`. 
Most of this has to be done manually. 
Documentation is provided as follows 

====================   ===================================
  :program:`nx2img`    manpage and HTML documentation
  :program:`img2nx`    manpage and HTML documentation
  :program:`qnx2img`   inline help and HTML documentation
  developers           only HTML documentation
====================   ===================================

In order to save time and effort to run several documentation systems in
parallel we have decided to do everything with Sphinx.


Building man-pages
==================

Manpages are built for :program:`nx2img` and :program:`img2nx`. The build is
started with 

.. code-block:: bash

    $ python setup.py build_sphinx -bman

which should create the files

.. code-block:: bash

    img2nx.1
    nx2img.1

in :file:`build/sphinx/man`.


Building HTML documentation
============================

The HTML documentation can be done with 

.. code-block:: bash

    $ python setup.py build_sphinx -bhtml

Which should create new files below :file:`build/sphinx/html`.


Building the QTHelp documentation
=================================

Building the QtHelp documentation is a bit more tricky. First 
start by running Sphinx with

.. code-block:: bash

    $ python setup.py build_sphinx -bqthelp

which would result in new files below :file:`build/sphinx/qthelp`. 
Aside from the HTML files you will find there

.. code-block:: bash

    NexusImageTools.qhcp
    NexusImageTools.qhp

use the :program:`qcollectiongenerator` program to create the compressed HTML
files and the collection file. Running the program in
:file:`build/sphinx/qthelp` with 

.. code-block:: bash

    $ qcollectiongenerator -o NexusImageTools.qhc NexusImageTools.qhcp

will create two new files 

.. code-block:: bash

    NexusImageTools.qhc
    NexusImageTools.qch

where the first one is the help collection and the second one the file with 
the compressed HTML files. 
As currently only :program:`qnx2img` makes use of the Qt help engine these
files should be copied to :file:`src/nexus_image_tools/qnx2img`.

.. note::

    Need a better procedure so that the files are copied automatically 
    to the required location.

    Currently we have to update the files manually and copy them to the 
    appropriate source folder.