Add support to generate the api documentation in Qt help format

Qt help files are used by Qt Creator and KDevelop, for example, to support
the development of Qt-based applications and libraries.

Generating api documentation in Qt help format is controlled by two
user specific options named --enable-qt-help and --with-qchdir (autotools)
and -DENABLE_QT_HELP and -DINSTALL_QCH_DIR (cmake).

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 0d00d6ede7f560d674e426d40ec2c4219f82c479..ec199df03846116327c46252224f71a5f5f4c0e9 100644 (file)
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -605,6 +605,7 @@ message("        installing system libs:   ${DBUS_INSTALL_SYSTEM_LIBS}         "
 message("        Building inotify support: ${DBUS_BUS_ENABLE_INOTIFY}          ")
 message("        Building kqueue support:  ${DBUS_BUS_ENABLE_KQUEUE}           ")
 message("        Building Doxygen docs:    ${DBUS_ENABLE_DOXYGEN_DOCS}         ")
+message("        Building Qt help docs:    ${DBUS_ENABLE_QTHELP_DOCS}          ")
 message("        Building XML docs:        ${DBUS_ENABLE_XML_DOCS}             ")
 message("        Daemon executable name:   ${DBUS_DAEMON_NAME}")
 if(WIN32)

diff --git a/Doxyfile.in b/Doxyfile.in
index f137750440572df703cbfbcff05e4fc1afa811c4..38baf5d8b45aa1441b49b3a2872efa0b7d767087 100644 (file)
--- a/Doxyfile.in
+++ b/Doxyfile.in
@@ -179,3 +179,11 @@ DOT_CLEANUP            = YES
 # Configuration::addtions related to the search engine   
 #---------------------------------------------------------------------------
 SEARCHENGINE           = NO
+
+#---------------------------------------------------------------------------
+# Configuration::qt creator help support
+#---------------------------------------------------------------------------
+GENERATE_QHP           = @DOXYGEN_GENERATE_QHP@
+QHP_NAMESPACE          = org.freedesktop.dbus
+QHG_LOCATION           = @DOXYGEN_QHG_LOCATION@
+QCH_FILE               = @DOXYGEN_QCH_FILE@

diff --git a/README.cmake b/README.cmake
index 13b928e8961d33b303240b9e0f82d1c3dc9ce969..e6bc9725cfafc43f1ec3e12051b4bfbba2a9d793 100644 (file)
--- a/README.cmake
+++ b/README.cmake
@@ -139,6 +139,10 @@ DBUS_ENABLE_ANSI:BOOL=OFF
 // build DOXYGEN documentation (requires Doxygen)
 DBUS_ENABLE_DOXYGEN_DOCS:BOOL=OFF
 
+// build qt help documentation (requires qhelpgenerator(-qt5));
+// set INSTALL_QCH_DIR for custom qch installation path
+ENABLE_QT_HELP:STRING=AUTO
+
 // enable bus daemon usage statistics
 DBUS_ENABLE_STATS:BOOL=OFF
 

diff --git a/cmake/modules/Macros.cmake b/cmake/modules/Macros.cmake
index fed1600770180475e1f910d03a034078f5313083..c594747e3b719ec1e010071b095e36658ca74e5e 100644 (file)
--- a/cmake/modules/Macros.cmake
+++ b/cmake/modules/Macros.cmake
@@ -200,3 +200,15 @@ macro(add_library_version_info _sources _name)
     # version info and uac manifest can be combined in a binary because they use different resource types
     list(APPEND ${_sources} ${CMAKE_CURRENT_BINARY_DIR}/versioninfo-${DBUS_VER_INTERNAL_NAME}.rc)
 endmacro()
+
+#
+# provide option with three states AUTO, ON, OFF
+#
+macro(tristateoption _name _default _text)
+    if(NOT DEFINED ${_name})
+        set(${_name} ${_default} CACHE STRING "${_text}" FORCE)
+    else()
+        set(${_name} ${_default} CACHE STRING "${_text}")
+    endif()
+    set_property(CACHE ${_name} PROPERTY STRINGS AUTO ON OFF)
+endmacro(tristateoption)

diff --git a/configure.ac b/configure.ac
index c0662b9a2525aca518a531aaa1dca0dc914aa0c8..e8522f646ac6856d20cda7e04909e189aa3d6e27 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -1244,6 +1244,39 @@ AC_SUBST([DBUS_GENERATE_MAN])
 AM_CONDITIONAL(DBUS_DOXYGEN_DOCS_ENABLED, test x$enable_doxygen_docs = xyes)
 AC_MSG_RESULT($enable_doxygen_docs)
 
+AC_ARG_WITH([qchdir],
+            AS_HELP_STRING([--with-qchdir=DIR], [Directory for installing Qt help file]),
+            [qchdir=$withval],
+            [qchdir="$docdir"])
+AC_SUBST([qchdir])
+
+AC_ARG_ENABLE([qt-help],
+              [AS_HELP_STRING([--enable-qt-help=auto|yes|no], [Build Qt help documentation])],
+              [],
+              [enable_qt_help=auto])
+AS_IF([test "x$enable_qt_help" != xno],
+      [AC_CHECK_PROGS([QHELPGENERATOR], [qhelpgenerator qhelpgenerator-qt5])],
+      [QHELPGENERATOR=])
+AS_IF([test "x$QHELPGENERATOR" = x && test "x$enable_qt_help" != xno && test "x$enable_qt_help" != xauto],
+      [AC_MSG_ERROR([Building of Qt help requested, but qhelpgenerator not found])])
+
+AC_MSG_CHECKING([whether to build Qt help documentation])
+AS_IF([test "x$enable_doxygen_docs" = xyes && test "x$QHELPGENERATOR" != x], [
+    enable_qthelp_docs=yes
+    DOXYGEN_GENERATE_QHP=YES
+    DOXYGEN_QHG_LOCATION="$QHELPGENERATOR"
+    DOXYGEN_QCH_FILE="$(pwd)/doc/api/qch/dbus-$VERSION.qch"
+  ], [
+    DOXYGEN_GENERATE_QHP=NO
+    enable_qthelp_docs=no
+  ])
+AC_SUBST([DOXYGEN_GENERATE_QHP])
+AC_SUBST([DOXYGEN_QHG_LOCATION])
+AC_SUBST([DOXYGEN_QCH_FILE])
+
+AM_CONDITIONAL([DBUS_QTHELP_DOCS_ENABLED], [test "x$enable_qthelp_docs" = xyes])
+AC_MSG_RESULT($enable_qthelp_docs)
+
 AC_CHECK_PROGS([XSLTPROC], [xsltproc])
 AM_CONDITIONAL([DBUS_HAVE_XSLTPROC], [test "x$XSLTPROC" != "x"])
 
@@ -1766,6 +1799,7 @@ echo "
         Traditional activation:   ${enable_traditional_activation}
         Building X11 code:        ${have_x11}
         Building Doxygen docs:    ${enable_doxygen_docs}
+        Building Qt help file:    ${enable_qthelp_docs}
         Building Ducktype docs:   ${enable_ducktype_docs}
         Building XML docs:        ${enable_xml_docs}
         Building launchd support: ${have_launchd}

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 6d4d991117df287e175bb66898c2a92ffa70a5de..1f47fa2acc06db4db4373a7dfea583ef0b0cf176 100644 (file)
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -8,6 +8,7 @@ add_custom_target(doc ALL)
 
 if(DOXYGEN_EXECUTABLE)
     option(DBUS_ENABLE_DOXYGEN_DOCS "build DOXYGEN documentation (requires Doxygen)" ON)
+    tristateoption(ENABLE_QT_HELP AUTO "build qt help documentation (requires qhelpgenerator(-qt5)); set INSTALL_QCH_DIR for custom qch installation path")
 endif()
 
 if(DBUS_ENABLE_DOXYGEN_DOCS)
@@ -18,6 +19,24 @@ if(DBUS_ENABLE_DOXYGEN_DOCS)
     else()
         set(DBUS_GENERATE_MAN YES)
     endif()
+    if(NOT DEFINED INSTALL_QCH_DIR)
+        set(INSTALL_QCH_DIR ${CMAKE_INSTALL_DATADIR}/doc/dbus)
+    endif()
+    find_program(QHELPGENERATOR_EXECUTABLE NAMES qhelpgenerator qhelpgenerator-qt5)
+    if(ENABLE_QT_HELP AND NOT ENABLE_QT_HELP STREQUAL "AUTO" AND NOT QHELPGENERATOR_EXECUTABLE)
+        message(FATAL_ERROR "Qt help requested but qhelpgenerator not found")
+    endif()
+    if(ENABLE_QT_HELP AND QHELPGENERATOR_EXECUTABLE)
+        message(STATUS "${QHELPGENERATOR_EXECUTABLE} found")
+        set(DOXYGEN_GENERATE_QHP YES)
+        set(DOXYGEN_QHG_LOCATION ${QHELPGENERATOR_EXECUTABLE})
+        set(DOXYGEN_QCH_FILE ${CMAKE_CURRENT_BINARY_DIR}/api/qch/dbus-${VERSION}.qch)
+        set(DBUS_ENABLE_QTHELP_DOCS ON PARENT_SCOPE)
+        install(FILES ${DOXYGEN_QCH_FILE} DESTINATION ${INSTALL_QCH_DIR})
+    else()
+        set(DOXYGEN_GENERATE_QHP NO)
+        set(DBUS_ENABLE_QTHELP_DOCS OFF PARENT_SCOPE)
+    endif()
     configure_file(../Doxyfile.in ${CMAKE_BINARY_DIR}/Doxyfile )
     file(GLOB dbus_files "${CMAKE_SOURCE_DIR}/dbus/*.[ch]*")
     add_custom_command(

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 831c08a1324238f5a1be6941d5fbcc2b4dc48c79..b2a7b52ad94120de2a43e5bc82923183994b7802 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -119,6 +119,10 @@ endif
 install-data-local:: doxygen.stamp
        $(MKDIR_P) $(DESTDIR)$(apidir)
        $(INSTALL_DATA) api/html/* $(DESTDIR)$(apidir)
+if DBUS_QTHELP_DOCS_ENABLED
+       $(MKDIR_P) $(DESTDIR)$(qchdir)
+       $(INSTALL_DATA) $(DOXYGEN_QCH_FILE) $(DESTDIR)$(qchdir)
+endif
 if DBUS_DUCKTYPE_DOCS_ENABLED
        $(AM_V_at)for x in $(YELP_STATIC_HTML); do \
                if test -e "$$x"; then \
@@ -138,6 +142,8 @@ uninstall-local::
        rm -f $(DESTDIR)$(docdir)/*.txt
        rm -f $(DESTDIR)$(htmldir)/*.png
        rm -f $(DESTDIR)$(htmldir)/*.svg
+       rm -f $(DESTDIR)$(apidir)/*.qhp
+       rm -f $(DESTDIR)$(qchdir)/dbus-*.qch
        rmdir --ignore-fail-on-non-empty $(DESTDIR)$(apidir) || \
                rmdir $(DESTDIR)$(apidir)
 endif

diff --git a/tools/ci-install.sh b/tools/ci-install.sh
index 01b8d669ba41d7b593e870e32213e9921144d7de..438cf99cdb85426fdba27cbec55d4e3da5dd79a2 100755 (executable)
--- a/tools/ci-install.sh
+++ b/tools/ci-install.sh
@@ -125,7 +125,7 @@ case "$ci_distro" in
 
         if [ "$ci_host/$ci_variant/$ci_suite" = "native/production/buster" ]; then
             $sudo apt-get -qq -y --no-install-recommends install \
-                qttools5-dev-tools \
+                qttools5-dev-tools qt5-default \
                 ${NULL}
         fi