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 _______________________________________________ Development mailing list [email protected] http://lists.qt-project.org/mailman/listinfo/development
