Hi everybody, TL;DR: We need to change the way Qt does documentation. A lot of things will change and we need help from everybody.
As mentioned by Lars: We should make sure the quality of the documentation for Qt 5.0 is as high as possible. To get and keep our documentation in shape for Qt 5.0 and beyond I think we will need to tackle the following problems: 1. The documentation is not modularized. 2. The documentation build system is hard to explain to people. (consequence of 1) 3. The different Qt modules have a completely different style of documenting. 4. The QDoc commands and functionality are not known well enough by people, which causes QDoc errors. 5. There is no real review process for documentation contributions. Modularizing the documentation is a process that will move a lot of files around and make some things impossible. The biggest consequence will be that we will have the same dependency chain as when compiling the modules. E.g. not allow circular dependencies in the documentation. Therefore there can be no links from the QtGui documentation to any class in QtWidgets, from QtWidgets to QtGui will work, since Widgets depends on Gui. This will also automatically break "Inherited by:" between classes in separate modules in the documentation. I have written down a possible method for modularizing the documentation at the end of this email. That should make the whole process more transparent. Issue 3 just needs people to clean up the documentation, writing guidelines to get this standard will be published on the Qt Project Wiki. For issue 4 I would like to point people to http://doc-snapshot.qt-project.org/qdoc/ this is the URL of the qdoc manual. If everybody follows what is written there and reports bugs about inconsistencies in the manual we should have a minimal influx of new qdoc errors. There are problems in qdoc (like not understanding C++ templates/macros and C++11 syntax for documenting QObject::connect), but we should not start putting Doxygen documentation commands in QDoc when there is a QDoc equivalent. I am also aware that we still need to change a lot of "old" documentation, like replacing all \gui commands with \uicontrol, which is quite a simple search/replace. Issue 5 needs thought and help from everybody. We will keep the normal reviewing process for documentation and we cannot enforce all documentation patches to be reviewed by native English speakers/technical writers. But when documentation changes we should all pay special attention to making it understandable to someone who is new to Qt. This has always been the focus of the Qt documentation and I think we should try to keep the same standard of documentation going forward. -- Modularized documentation proposal Let's use qtbase as an example, since that needs the global content such as CSS and default qdocconfs. - Source code stays where it is now under /src. - Global documentation (such as CSS Files and default qdocconf templates) goes into /doc/global. This will be copied to QT_INSTALL_DOCS/global to be used by the other repositories. modules inside qtbase will use relative links to the /doc/global folder. - Individual modules have their documentation in /src/[conveniencename]/doc. For example: "/src/corelib/doc". Documentation .qdoc files will stay under "src" in that folder, snippets will stay under "snippets", etc. - Images will go in /src/[conveniencename]/doc/images, cross-module images will not be allowed (unless you copy them into multiple folders). - The [modulename].qdocconf will be in the top-level directory for the module. For QtCore this means that the qdocconf file will be qtbase/src/corelib/doc/qtcore.qdocconf. - Documentation output will be put in /doc/html/[modulename]. The whole /doc/html/[modulename] folder will be copied to QT_INSTALL_DOCS/[modulename] - 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. The easiest thing would be to use the full modulename, so qtcore instead of just core. This means that you put "depends += qtcore" in the qtgui.qdocconf 2. We could then implement an -indexdir CLI option/variable which points to the directory containing all documentation and let qdoc look for /[modulename]/[modulename].index under that folder, 3. Then we will have to set-up the .pri files to let indexdir point to qtbase/doc/html for the modules in qtbase and QT_INSTALL_DIR/doc for the other modules. So when building qtgui qdoc will be called with "qdoc -indexdir doc/html doc/gui/qtgui.qdocconf". This should make it find /doc/html/qtcore/qtcore.index when you put depends += qtcore in the qtgui.qdocconf. 4. A problem will occur when you have other repositories that contain multiple modules. (such as qtpim and qtdeclarative) So there we need to specify 2 -indexdir options, QDoc should check the timestamp when there are 2 conflicting index files and use the newest one. - In the case of repositories with only one module we will not have the [conveniencename] folder level, so for instance Qt XML Patterns will have /doc/qtxmlpatterns.qdocconf - We will need to add the necessary "make [modulename]-docs" commands etc. in .pri files. A working prototype for QtCore can be found in http://codereview.qt-project.org/#change,20696 (depends on change 23020 for compilation). If you cherry-pick that change and run qdoc doc/corelib/qtcore.qdocconf in qtbase the output will be visible in doc/html/qtcore/. Since QtCore does not depend on anything there is no "depends" in the qdocconf necessary. Casper _______________________________________________ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development