Recommendations for 3rd-party QCH file installation folder for easy discovery?

Friedrich W. H. Kossebau kossebau at kde.org
Wed Nov 23 17:08:56 UTC 2016


Hi,

as this also affects (at least should :) ) KDevelop, also asking here:

Two questions to anyone working on/with QCH files:

Q1: what would be a good system path pattern (on *nixoid systems) for Qt-based 
libraries to install their QCH files to?

Q2: And would/could there be some way to have 3rd-party QCH files 
automatically added to KDevelop, Qt Assistant & Co. on installation, to spare 
the user the additional manual step?


For Q1, I see all the Qt ones are on my system at
        /usr/share/doc/packages/qt5/*.qch

So far I would have guessed
        /usr/share/doc/$lib/$lib.qch
might be a good location. So what patterns do people use for their QCH files 
when delivering to others as part of an install?


For Q2, having to manually add all QCH files one-by-one to KDevelop & Co. 
does not nicely scale if there are a dozen and more 3rd-party QCH files (think 
e.g. all the non-KF5 and KF5 libs created in the KDE community).

Would it perhaps make sense to have some registration system, so QCH files can 
register themselves somewhere, so KDevelop & other documentation 
viewers know what is present on the system?
Would some simple sym-linking into some generic dir make sense for a start? 
The /usr/share/doc/packages/qt5 perhaps should be reserved to original Qt 
ones, but perhaps some separate generic dir like
        /usr/share/doc/qch
would work? And additionally something based on ENV vars, to enable 
automatically adding more default QCH dirs to KDevelop & Co.?


Background:
I am currently working on adding QCH support to the buildsystem for all the 
libraries of the KDE Frameworks (and other (KDE) library products), for the 
generation of QCH files during builds (https://phabricator.kde.org/D2854).

This is done with the goals that the API documentation of KDE Frameworks 
libraries can be viewed/used offline with KDevelop, Qt Assistant & Co, and 
that packagers/distributors of those libraries automatically from the build 
also have a QCH file matching the very API version of the library for 
packaging (& inclusion into in any package update mechanism).

The implementation of this support is done by new CMake macros which for now 
make use of the QCH generation feature of doxygen. The macros even support the 
automatic qthelp:// linking to documentation of base libraries, like the Qt 
ones. Though that feature needs some fixes in KDevelop for non-Qt QCH files, 
see https://bugs.kde.org/show_bug.cgi?id=372747)

So soon there will be dozens of QCH files available which currently would each 
need manual work by the user to have them added to KDevelop & Co. Not perfect!

Cheers
Friedrich



More information about the KDevelop-devel mailing list