API docs QCH files: needs patched released doxygen & Qt Assistant using QtWebKit

[Friedrich W. H. Kossebau]

Hi distributions,

to improve developer experience with libraries created in the KDE community 
(like the KDE Frameworks, but also others) there is work done to create off-
line documentation in the QCH format (during the build), to integrate nicely 
with the Qt off-line documentation.

Just, there are some issues with the current tool chain which need some 
intervention from you, the distribution packagers. Please consider to do the 
following:


1) Doxygen needs a patch to not create broken QCH files

Doxygen in versions <unknown> to 1.8.12 (latest release at time of writing) 
misses to include some files with the generated QCH file (cmp. https://
bugzilla.gnome.org/show_bug.cgi?id=773693).
A fix has been already applied to the development version of doxygen. Ideally 
that fix would be applied also as patch to your currently packaged version of 
doxygen.
Chances are good the fix applies cleanly also to older versions. openSUSE 
Tumbleweed has that already, against latest 1.8.12:
https://build.opensuse.org/package/view_file/openSUSE:Factory/doxygen/doxygen-fix-QCH-files.patch?expand=1


2) Qt Assistant needs to be built with QtWebKit for QCH files by doxygen

Qt Assistant is often only built with QTextBrowser, especially now that 
QtWebKit is no longer official part of Qt>=5.6. Doxygen though uses lots of 
HTML5 (incl. hardcoded JavaScript), which results in broken/unusable display 
with QTextBrowser (cmp. https://bugzilla.gnome.org/show_bug.cgi?id=773715).
Sadly there is no fix for doxygen yet or even worked on to my knowledge, as 
this needs bigger changes. Switching to another tool like qdoc possibly needs 
bigger work on all the API annotations in the code and might have other 
implications, not investigated yet.
So as intermediate solution it would be good if distributions would build Qt 
Assistant with QtWebKit (again). This is decided by the qmake system by the 
presence of QtWebKitWidgets at build time, from what I understand (see
http://code.qt.io/cgit/qt/qttools.git/tree/src/assistant/assistant/
assistant.pro)
Using Qt WebEngine instead is still only at patch state and only for Qt 
Creator: https://codereview.qt-project.org/112390
See also bug filed with openSUSE: https://bugzilla.suse.com/show_bug.cgi?
id=1011355


For the related work here in KDE see the review request "New: ECMAddQch, for 
generating qch & doxygen tag files" at https://phabricator.kde.org/D2854
Variants of these macros have already been committed to the development 
branches of KDb, KProperty, KReport, KDiagram (KChart/KGantt) (all to be 
dropped for the ECM macros, once part of min. required ECM version).
So it would be nice if the tool chain is already improved, once that code gets 
released in the near future.
(Note: the creation of QCH in all these examples is controlled by a CMake 
option BUILD_QCH, which if OFF by default and also listed in the "Features" 
cmake summary log)

Cheers
Friedrich