Build documentation¶
Necessary tools¶
In order to be able to build the documentation, you need to have some tools installed on your computer:
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.
You will find Doxygen under http://www.stack.nl/~dimitri/doxygen/. Goto the download section and get the latest release. Windows users can directly download the binaries provided as setup version. Install Doxygen on your computer.
Python-Package Sphinx
The real user documentation is created in itom using a python script that needs the Python package Sphinx (http://sphinx-doc.org/). Sphinx itsself requires other python packages installed on your computer. Therefore we suggest to get Sphinx by the python package distribute that is able to download the latest version of Sphinx including all depending packages. For the Windows operating systems, distribute also installs an application easy_install in the PythonScripts directory. Easy_install can be called from any command line in order to get Sphinx.
In order to get distribute and easy_install, execute the following steps:
Go to http://pypi.python.org/pypi/distribute and download the file distribute-x.x.xx.tar.gz and unzip to any folder on your computer.
Open a command line (cmd) and change to the folder (command cd) where you unpacked distribute.
Execute the following command (Replace with your correct python-directory):
C:/python32/python.exe distribute_setup.py
Now distribute is installed. When done, you can delete the folder the files were extracted to.
Verify that the application easy_install.exe is now available in your python/scripts directory (Windows only)
Now you can use easy_install in order to get Sphinx:
Open a command line (cmd) and change to the subfolder Scripts of your Python installation.
Execute the following command:
easy_install -U Sphinx
Now Sphinx is downloaded and Sphinx and its depending packages are installed.
You can also manually download and install Sphinx and its depending packages. Setup-versions of Sphinx, Pygments, Jinja2, docutils... are also available from http://www.lfd.uci.edu/~gohlke/pythonlibs/. 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 lies in the bin-folder of you 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 create_doc.py 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 pathes to these tools are automatically inserted into the script create_doc.py.
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 the 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 and in the folder plugins or any subfolder.
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.