[Development] Documentation and Modularization

[Gladhorn Frederik]

Hi,
while we all love our documentation we also need to work on polishing it some more ;)
Today there was a discussion in Oslo about the "how to link between modules" problems we're facing with qdoc.

I'll try to illustrate the problem and show the solution we would like to propose.
We have two conflicting goals:
1 - making documentation be modular, so that it can be built easily within a Qt module
2 - making links to other parts of the documentation between modules

The following is about the essential modules. For add-on modules, documentation should be self-contained, but can reference to all (build-) dependencies.
Generally linking to build-dependencies is fine.
At the moment there are two ways of building the docs correspondingly.

1 - Running "make docs" will give you a module's documentation. The problem with this approach is that you get many linking errors since you limit yourself to the module itself and other modules that have already been built. "Forward" links pointing out of the module will not work. As example, you cannot in QtGui link to Widgets or Quick. For a while we tried to cut all of these forward pointing links, but it simply seems too limiting, no links to overview documentation are possible then for example. The configuration for qdoc is found in each module in qdocconf files. (This approach will be called building "modular docs" from now on.)

2 - Running "make online_docs" in the qtdoc repository, after running "qmake && make qmake_all" in each module. This is the "monolithic" build of the documentation, it uses its own set of qdocconf files, all gathered in the qtdoc repository and linking to all modules that were registered before in qtbase/mkspecs/modules. For developer-builds that works in the build directory, for regular builds this means you need to make install for all modules to be able to build the docs this way.



So what are the good/bad things about the two approaches?
1 - modular docs:
- it's almost impossible to link between modules, but we need to.
+ it's convenient, we can simply run make docs when developing qt and check that the docs are ok

2 - monolithic docs:
+ links work
- you need all modules, potentially installed


As you can see, option 1/modular is great for people hacking on Qt, we even want to make the make docs step part of the normal building of Qt, so that you learn about new doc errors you introduce.
With the monolithic build you get a full set of documentation that actually has working links.
For the users of Qt it is more important to have documentation with working links that is complete.

Since we don't see a way to fix the modularized build of the docs without big issues (predictive links seem hard to get right and we couldn't show warnings about them easily), we propose to actually make use of a mixed approach to get the documentation for Qt 5.0 in shape (it's about time).
For developers we want to keep the modular approach to make their lives easy and make it convenient to actually run qdoc. In order to generate the documentation used on the website/sdk etc we would use the monolithic approach.
In order to not drown in warnings for links that could not be resolved, we would implement one feature in qdoc: "external" links. These will simply be ignored when running make docs in a module if they cannot be resolved. This gets rid of the warnings and since the marking as external is explicit. For the monolithic build of the docs on the other hand we'd warn about all missing links.
The exact syntax for how an external link would look like needs to be figured out still. The best we came up with right now is prefixing links with "external_link::" which would work with \l external_link::QWidget::show() and \sa etc. Actually the prefix most certainly will look different, let's see what experiments with qdoc yield.

PS: ideally the monolithic approach should just use the qdocconf files from the modules, currently all of them are duplicated. This should be solved, but it's not as important as getting the documentation build working.
This means that long term we get rid of the current way of running "make online_docs" in the doc module and there just run all modules make docs twice - once creating index files, in a second run creating the actual documentation with working links (needs work on qdoc).

Cheers
Frederik

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120919/85626213/attachment.html>