[Development] Towards a Qt 5 beta: Documentation

[lars.knoll at nokia.com]

On 4/12/12 7:27 PM, "ext casper.vandonderen at nokia.com"
<casper.vandonderen at nokia.com> wrote:

>>> There are 2 main problems with the current system:
>>> 1. Nobody was running "make docs" on their local machines (and
>>>verifying the
>>> output). There are qdoc errors that were put in by developers last
>>> December. Having the documentation modularized will at some point
>>> (hopefully soon) allow us to put documentation generation in the CI
>>>system.
>>> This would allow us to catch patches causing qdoc errors.
>>> 2. It was/is completely unclear how the system works, there hasn't
>>>been any
>>> QML documentation at http://doc-snapshot.qt-project.org/5.0/ for
>>>multiple
>>> weeks now (I believe 4, maybe more).
>>
>> But none of those problem will be fixed by modularizing the docs by
>>libraries.
>> Or am i missing something?
>>
>>
>> (putting make docs in the CI is a good idea)
>
>The CI system the documentation will be built per repository, that is
>true, but there might be users who only want to build a specific set of
>libraries with documentation and the extra step of granularity will not
>make a difference (in my opinion), since the only difference would be a
>few extra qdocconf files and make targets.

In addition, this is a good practice. We might later on split out certain
parts from the qtbase repo, and I want this to be possible. The second
side is that users should *not* be exposed to our repo structure.

If we have uplinks one place people expect them to work everywhere. But
that's completely incompatible with a modular structure, where one can add
and remove libraries from the SDK (something we need to aim for in the
longer term).

I can't see a way how you could possibly have a complete list of classes
inheriting e.g. QObject in such a modular world. And I don't think it's
desirable neither.
>
>I also think that adding the documentation build closer to the source
>build (we could add the "make corelib-docs" target to corelib.pro) will
>make the whole system more transparent and (psychologically) easier to
>use.

Or simple 'cd src/corelib; make docs' ;-)

Cheers,
Lars