Saturday, April 10, 2010

Setting up KDE API Documentation

Since last few months, I have been playing around with KDevelop which is a KDE based IDE for C/C++ any many other languages. Its a large C++ codebase and navigating through all the files, classes is quite difficult with usual VI + cscope combination. The most lacking part is a readily accessible KDE API documentation which is almost essential, no matter what component you are working on. There is a KDE API reference site but searching there for every reference is very cumbersome. So, I decided to setup a local API reference. Steps:

  • Checkout sources
  • Generate API documentation from sources
  • Import documentation in Qt Assistant: It provides nice interface to navigate through all the documentation
  • Get KDevelop4 working from sources (to hack KDevelop itself!) [explained here]

Checkout Sources

We will checkout sources for kdelibs, kdesdk, kdevplatform and kdevelop. I just want to hack on KDevelop, so you may need checkout additional repositories depending on what you want to do. Instructions for checkout of different repositories and branches is present here.

We’ll checkout everything in $HOME/repo/ (of course, you can change it to anything you want).

mkdir $HOME/repo; cd $HOME/repo

svn co svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs
svn co svn://anonsvn.kde.org/home/kde/trunk/KDE/kdesdk

git clone git://gitorious.org/kdevelop/kdevplatform.git
git clone git://gitorious.org/kdevelop/kdevelop.git

Generate API Documentation

Now we’ll generate documentation from sources in .qch format – which is a single compressed file containing all the documentation. These qch files will be later imported in Qt Assistant.

First, download script to generate these qch files. This is a slightly modified version of the script included with kdesdk (kdesdk/scripts/kdedoxyqt.sh). This modified version works for all the source trees listed above and also generates class diagrams etc. Now, generate documentation for each source tree using this script:


cd ~/repo
cd kdesdk; kde_gendoc.sh; cd ..
cd kdelibs; kde_gendoc.sh; cd ..
cd kdevplatforms; kde_gendoc.sh; cd ..
cd kdevelop; kde_gendoc.sh; cd ..

This will generate a .qch file in each of the trees (<tree>/apidocs/qch/<tree>.4.x.qch). For example, kdesdk/apidocs/qch/kdesdk.4.x.qch

All these qch files total around 120MB.


Import In Qt Assistant


Now import all these qch files in Qt4 Assistant. Start the program and goto: Edit –> Preferences –> Documentation tab –> Add… and select a qch file. Repeat this for all four .qch files and you are done.

qt4_assistant_with_kdedoc

Figure 1: Qt Assistant with all the KDE API documentation.

You should now have all the KDE documentation listed in ‘Contents’. Now any class reference is quick and easy with lightning fast Qt Assistant’s Index.

That’s it!

2 comments:

  1. Argh. Where is the script? Can't download it.

    ReplyDelete
  2. I discontinued all KDE related projects, so the script mentioned was also deleted. Anyways, I found a version of the same in my backup but it may have some issues. It's now uploaded here:

    https://docs.google.com/leaf?id=0B1GumAT0-S9UY2IxZTYxODctZWQ1ZS00ZmI1LThlYmEtN2E0NzJjMTY3NDJl&hl=en_US

    Thanks.

    ReplyDelete