[Development] Towards a Qt 5 beta: Documentation

[casper.vandonderen at nokia.com]

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