Documenting a Qt Application

[dvmorris]

I am having a really hard time deciding how to create user documentation for my application built with Qt. I would like it to be displayed at html files with the Qt Assistant, and I would love to have a tool that generates the qt assistant configuration file automatically.

I have looked into docbook recently, and I cannot for the life of me get it to work on my macbook pro. The instructions tutorials I've found are either incomplete or they return a 404 error. Is DocBook still a legitimate way to do this kind of thing?

I would love to find out how other people do user documentation for their projects. I am doing my developer documentation with Doxygen, and that is working perfectly, but DocBook is giving me hell.

I found this script from a few years ago:

http://lists.trolltech.com/qt-intere...ad01422-0.html

but i can't seem to get it to work either.

[wysota]

So why don't you stick with Doxygen?

[dvmorris]

Well is that really suited for a user guide? I don't want the user to see diagrams of the code structure or look at source code or anything like that.

What do other popular open source projects do for user guides? it looks like blender uses docbook but i'm not quite sure where there source files are in the files i grabbed from their cvs.

[wysota]

Surely docbook is the most popular, but if your structure is simple, you can create the html manually or semi-automatically with software not dedicated to documenting applications.

[dvmorris]

for how popular docbook is supposed to be, it is incredibly difficult to figure out for some reason. Is there an app out there that does everything all in one package, like creating the files, converting to html, pdf, etc...

I found XMLEditor and Oxygen, but those don't seem to come with that functionality in the demo or free versions. Is there an open source or free alternative?

[wysota]

Maybe you should just go for xslt? There are probably XSL templates available that fit your needs, so you won't even have to write your own XSLT file. And implementing a simple template that will generate a dcf file should be trivial.

[dvmorris]

ok, i'll look into that. Thank you for your help.