Using KApidox

written on Monday, May 26, 2014

What is KApidox?

Good libraries come with good documentation. It is therefore essential for KDE Frameworks to provide comprehensive online and offline documentation.

KApidox is a set of tools used to generate KDE Frameworks documentation. These command-line tools use Doxygen to do most of the work. The following tools are provided:

• kgenapidox: Generate documentation for a single framework
• kgenframeworksapidox: Generate documentations for all frameworks as well as the landing page which lets you list and filter frameworks by supported platforms
• depdiagram-prepare and depdiagram-generate: Generate dependency diagrams (requires CMake and Graphviz)

In this post I am going to talk about kgenapidox, which is the tool you are most likely to run by yourself. While it is often good enough to read documentation online through api.kde.org, it is also useful to be able to generate documentation offline, for example because your Internet access is slow or you are currently offline, or because you want to improve the existing documentation. kgenapidox is the tool you want to use for this.

Installing

The first thing to do is to install KApidox. The code is hosted in a Git repository on KDE infrastructure. Get it with:

git clone git://anongit.kde.org/kapidox

KApidox tools are written in Python. In addition to Doxygen, you need to have the pyyaml and Jinja2 Python modules installed. If your distribution does not provide packages for those modules, you can install them with:

pip install --user pyyaml jinja2

KApidox itself can be installed the standard Python way using python setup.py install. You can also run KApidox tools directly from the source directory.

Generating Documentation

You are now ready to generate documentation. Go into any checkout of a framework repository and run kgenapidox:

$ kgenapidox
19:08:48 INFO Running Doxygen
19:08:49 INFO Postprocessing
19:08:50 INFO Done
19:08:50 INFO Doxygen warnings are listed in apidocs/doxygen-warnings.log
19:08:50 INFO API documentation has been generated in apidocs/html/index.html

As you can see from the command output, the documentation is generated by default in the apidocs/html directory. You can now open the documentation with your preferred browser. kgenapidox can also tell Doxygen to generate man pages or Qt compressed help files. Run kgenapidox --help for more details.

Improving the Documentation

If you maintain a framework, contribute to the KDE Frameworks project or want to get involved, open the warning file generated in apidocs/doxygen-warnings.log and start fixing! Improving the documentation of a framework can make it much more useful, so it is a very welcome contribution.

Vim tip: The warnings file can be loaded in the quickfix list with :cfile apidocs/doxygen-warnings.log.