[Development] Towards a Qt 5 beta: Documentation

[casper.vandonderen at nokia.com]

Hi,

> 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).

I have been thinking about this problem for some time, and while it is technically possible from a qdoc side to implement the whole system like this: I don't see the CI system handling anything like this, what we could do is have a previous run of all the index files somewhere for the CI system to find, but that would theoretically open up the possibilty that I remove a documentation \class from QtCore, but it will still be found in the index. The missing file will only show up when you run qhelpgenerator to generate the QCH files.

And I haven't even talked about the qhelpgenerator/QCH process yet, because that thing is still in qttools and can therefore not be run in the CI for qtbase.

>> - 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.

Adding this information extra in the qdocconf file will not be that harmful I think because we don't change the dependency tree that often anymore. 
But I would be grateful if you would make a plan on how to turn qdoc into a mini-qmake so that qdoc can parse the .pro/sync.profile, so that we don't need the depends. Because that would probably also mean that you have to run "qdoc [module.pro] [module.qdocconf]", or do you see that differently?


Casper