Build documentation

Necessary tools

In order to be able to build the documentation, you need to have some tools installed on your computer:

  1. Doxygen

    Doxygen is a source code documentation tool, that parses your C++-source code and extracts the documentation strings for all methods. Additionally, it displays the entire class- and file-structure of your project. itom‘s user documentation sometimes uses results from Doxygen in order to show relevant C++-structures for programming plugins.

    Windows users can download the binaries as setup from Under linux the easiest way is to get the latest doxygen package that is available for your distribution.

  2. Python-Package Sphinx

    The real user documentation is created in itom using a python script that needs the Python package Sphinx ( Sphinx itself requires other python packages installed on your computer. For windows users, we therefore suggest to obtain Sphinx via the python package tool pip or easy_install.

    For pip, download the script from and save it on your harddrive. Then execute this script with your desired python version either by double-clicking on it, or open a command line and call something like:


    Then use the command line again and change to the directory:

    cd C:/python32/scripts

    and execute:

    pip install sphinx


    pip install --ugrade sphinx

    if you want to upgrade sphinx. All dependent python packages will be installed, too.

    You can also manually download and install Sphinx and its depending packages. Setup-versions of Sphinx, Pygments, Jinja2, docutils... are also available from However, you then need to separately install all depending packages of Sphinx.

Run doxygen

In your build-directory of itom, you will find a folder docs. Open its subfolder doxygen. There you will find a document itom_doxygen.dox. This document contains absolute pathes to the source directories of itom‘s sources. Run doxygen with this document in order to create the source code documentation.

On Windows computers, the easiest way to do this is open itom_doxygen.dox with the tool doxywizard that is located in the bin-folder of your doxygen installation. In doxywizard go to the run-tab and click on the run-button.


After the build process, a folder xml is created in the doxygen subfolder of the docs folder. This xml folder is required afterwards.

Run Sphinx

Now open itom and execute the script in the folder docs/userDoc of the build-directory. The default-builder of the documentation is qthelp. If you also want to build the documentation for other builders, you can change the list buildernames. The following values are possible:

qthelp -> default qthelp format for opening the documentation within itom
htmlhelp -> creates a chm-help format on Windows only
latex -> creates a pdf-document using latex. You need to have latex installed on your computer

The output of all build processes are located in the folder docs/userDoc/build/<buildername>. The locations of the Windows html-help generator or the latex interpreter are detected when running CMake for the itom-project. The absolute paths to these tools are automatically inserted into the script

Show documentation in itom

When clicking the help-button in itom or pressing F1, Qt‘s assistant is opened with a set of documentation files. At first, itom checks your itom installation for various documentation files. Their latest version is then copied into the help folder of the build-directory. The search is executed for all .qch-files that are located in the docs/userDoc-directory.

After having copied the files, a collection-file is generated (containing all qch-files) and displayed in the assistant. If you have a setup version of itom, the help-folder already contains a compiled documentation file, that is displayed in this case. Please note that the file check is only execute once per itom session. Restart it in order to redo the check.