[Development] Towards a Qt 5 beta: Documentation

[Lincoln Ramsay]

Hi.

In general I applaud this effort.

I'm going to talk about some of the doc things Qtopia had. Most of this 
came from our (infamous for being unmaintainable) mkdocs script. Given 
the reputation that script had I'm not about to suggest we implement 
things similarly in Qt but perhaps the ideas are worth something.

In an effort to stop people from ignoring doc errors (by not building 
docs), we developed a system that automatically built the docs for a 
given directory when running make there. It was very quick (compared to 
building all docs) though its output wasn't very useful but we only 
cared about the errors anyway. QtSensors (and I guess other Qt modules) 
already have a similar-ish system in place where they can build their 
docs separately from the rest of Qt. Again, the result isn't very useful 
compared to a full doc build but it's very fast and great for reviewing 
doc changes as they're happening (though it's not automatic).

We had cross-module links in both directions. We achieved this by 
running qdoc twice per module. Once to get the .index (used for 
resolving links) and again to build with the other modules' .index 
files. The only way to avoid doing things twice would be to have more 
intermediate steps in the doc building process (ie. generate indexes, 
etc for everything then bring those together into a final product and 
resolve all the links then).

> - For cross-linking we need to do a few things (None of this is
> implemented yet):
> 1. We need to add a "depends" qdocconf variable, where you list the
> modules you depend on.

Why?! We already have our dependencies stated in the sync.profile and 
module .pro files. Duplicating this information just causes a 
maintenance burden. Allowing explicit dependencies on docs (where there 
is no dependency between modules) may make sense but dependencies 
derived from the build should be extracted from the build.

-- 
Lincoln Ramsay - Senior Software Engineer
Qt Development Frameworks, Nokia - http://qt.nokia.com/