[Development] Documentation sessions

[casper.vandonderen at nokia.com]

Hi,

At the Contributors Summit we held 2 documentation sessions. The main
points for discussion were the current state of the documentation,
examples and the cross-referencing of documentation. I am probably
forgetting some point here, so please add them in a follow-up message.

Current state:
- Most of the Qt essential modules have been modularized.
- There is little consistency between the documentation modules.
- There is no "make install" target for the modularized documentation yet.

Examples:
- Demo applications do not belong in the documentation, but should be on
DevNet.
- There are currently too many examples.
- Examples should show more advanced functionality of a class, simple
classes should have their examples in the class reference and not a
separate example application.
- Multiple examples should not demonstrate the same functionality with
only minor changes (no separate examples that demonstrate how to paint
text in one and a rectangle in the other).
- Examples should not use C++11 functionality, unless they are examples
that demonstrate how to use Qt with C++11 (since older compilers might not
support everything)
- Example documentation should be built together with the API
documentation for that module.
- Examples should stay in the examples folder, but example documentation
should move to the examples/doc folder (it is currently in
doc/src/examples)

Cross-referencing:
- Probably there should be an option for both a monolithic build and a
per-module build.
- Some special format for forward-referencing will be hard to implement,
especially since some of the oft-used modules might not be available on
all platforms (QtWidgets). At this point in time not allowing forward
references seems to make the most sense.
- Building examples at the same time as reference should limit the amount
of cross-referencing errors.


Getting QDoc in the CI system is also one of the points discussed, but
this needs some more discussions with the CI team.


Casper