xcode-tokens-from-qtdocs

Qt API Documentation in XCodexcode-tokens-from-qtdocs

Qt Documentation -> AppleRef Tokens.xml generatora python script to parse Trolltech's Qt HTML Documentation for tokens to be used in Xcode

ContextFor developing Qt (Nokia's / Trolltech's cross platform C++ application framework) on a Mac, there are some useful tools, like qmake, which can help you to generate an Xcode project through this command:% qmake -spec macx-xcode

Also the Qt Frameworks installs itself nicely in the system, so Xcode can easily compile your Qt project and can even do the code-completion for you. However, the integrated documentation services in Xcode are not so easily supported right out of the box. And as a avid Mac developer and Xcode user, I missed those features severely, trying to develop Qt on my machine.

Why the Tokens.xmlI searched the web and found this nice How To integrated the Qt documentation in Xcode 3.0. One thing was still missing though: API search. With the help of Yan Shapochnik's explanation you get a full text search to the Qt docs from within Xcode. But even more useful is Xcode's API documentation service. E.g. API search allows you option-click on a term in the code editor and directly open the documentation about that class or method in the Documentation window.

To get the API search integrated in Xcode, it needs a Tokens.xml file. Basically this file lists all the API terms (tokens), that can be looked up, and describes some context about the token: whether it's a class or a function; what's its scope etc etc. Such a Tokens.xml file doesn't exits for Qt's Documentation, so we'll have to make one.

I found parsing every Qt html doc page for classes, methods, functions and other terms much to difficult and too much work. So I whipped together a very simple python script which just does some of it. So the resulting Tokens.xml file is not perfect and all-containing, but at least it gets us somewhere halfway. And I think it will cover for 80% of all the terms you want to look up in your code.

How to use thisIf you are using Qt 4.4.1, as I am, you can just copy my Tokens.xml file from the svn into the same location as the Nodes.xml file from Yan's tutorial and run docsetutil.

If you have an other version of Qt, you'll need to make the python script run on your own machine. For this you'll have to:

copy the functions.html and the classes.html file from the documentation into your working folder clean them up quit a bit until treeElement can parse them correctly (remove the headers and footers, make a clear root node, remove the  s from the html ...). E.g. my functions.html looks like this:


DTDHandler: QXmlReader
...


run the python script until there are not too many errors and unprocessable stuff left copy the resulting Tokens.xml to the ~/Library/Developer/Shared/Documentation/DocSets/com.trolltech.qt.4.4.1.docset/Contents/Resources folder. and run /Developer/usr/bin/docsetutil index com.trolltech.qt.4.4.1.docset ConclusionThis docsetutil tool finds 13467 tokens (and ignores 114), on my version. I found this enough for my needs. I know this python code is one big hack. And the code is very ugly indeed.

But I found it useful enough to not only put the resulting Tokens.xml file here, but also the python script to generate that file yourself.

Tags

  python utility devtool qt documentation xcode

Share