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.
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-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.
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.
You are now ready to generate documentation. Go into any checkout of a framework repository and run
$ 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