[FEATURE] Option to build & install QCH file with the public API dox

Using the new extra-cmake-modules module ECMAddQch (since 5.36.0)
this adds the option to automatically build and install a file
in QCH format with the docs about the public API, which then can be
used e.g. in Qt Assistant, Qt Creator or KDevelop.

Additionally the installed cmake config files will be extended
with a target KF5Config_QCH containing information about how to "link"
into the generated QCH file, which then can be used in the cmake build
system of other libraries building on this library, by
simply listing this target in "LINK_QCHS" of their ecm_add_qch() usage.
And a respective doxygen tag file with all the metadata about the
generated QCH file and used for the "linking" will be created and
installed.

Pass -DBUILD_QCH=ON to cmake to enable this.

5 files changed, 50 insertions, 0 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 65eef063..2626b775 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -23,6 +23,10 @@ include(ECMSetupVersion)
 include(ECMGenerateHeaders)
 include(ECMMarkNonGuiExecutable)
 include(ECMPoQmTools)
+include(ECMAddQch)
+
+option(BUILD_QCH "Build API documentation in QCH format (for e.g. Qt Assistant, Qt Creator & KDevelop)" OFF)
+add_feature_info(QCH ${BUILD_QCH} "API documentation in QCH format (for e.g. Qt Assistant, Qt Creator & KDevelop)")
 
 ecm_setup_version(PROJECT VARIABLE_PREFIX KCONFIG
                         VERSION_HEADER "${CMAKE_CURRENT_BINARY_DIR}/kconfig_version.h"
@@ -42,6 +46,16 @@ endif()
 # create a Config.cmake and a ConfigVersion.cmake file and install them
 set(CMAKECONFIG_INSTALL_DIR "${KDE_INSTALL_CMAKEPACKAGEDIR}/KF5Config")
 
+if (BUILD_QCH)
+    ecm_install_qch_export(
+        TARGETS KF5Config_QCH
+        FILE KF5ConfigQchTargets.cmake
+        DESTINATION "${CMAKECONFIG_INSTALL_DIR}"
+        COMPONENT Devel
+    )
+    set(PACKAGE_INCLUDE_QCHTARGETS "include(\"\${CMAKE_CURRENT_LIST_DIR}/KF5ConfigQchTargets.cmake\")")
+endif()
+
 include(CMakePackageConfigHelpers)
 
 configure_package_config_file("${CMAKE_CURRENT_SOURCE_DIR}/KF5ConfigConfig.cmake.in"
diff --git a/KF5ConfigConfig.cmake.in b/KF5ConfigConfig.cmake.in
index d434c88e..f8e5eb0b 100644
--- a/KF5ConfigConfig.cmake.in
+++ b/KF5ConfigConfig.cmake.in
@@ -3,6 +3,7 @@
 # Any changes in this ".cmake" file will be overwritten by CMake, the source is the ".cmake.in" file.
 
 include("${CMAKE_CURRENT_LIST_DIR}/KF5ConfigTargets.cmake")
+@PACKAGE_INCLUDE_QCHTARGETS@
 
 include(CMakeFindDependencyMacro)
 find_dependency(Qt5Xml "@REQUIRED_QT_VERSION@")
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 916d51fb..998a1d52 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -3,3 +3,32 @@ add_subdirectory(gui)
 add_subdirectory(kconfig_compiler)
 add_subdirectory(kconf_update)
 add_subdirectory(kreadconfig)
+
+if (BUILD_QCH)
+    ecm_add_qch(
+        KF5Config_QCH
+        NAME KConfig
+        BASE_NAME KF5Config
+        VERSION ${KF5_VERSION}
+        ORG_DOMAIN org.kde
+        SOURCES # using only public headers, to cover only public API
+            ${KConfigCore_APIDOX_SRCS}
+            ${KConfigGui_APIDOX_SRCS}
+            "${CMAKE_SOURCE_DIR}/docs/options.md"
+        MD_MAINPAGE "${CMAKE_SOURCE_DIR}/README.md"
+        LINK_QCHS
+            Qt5Core_QCH
+            Qt5Xml_QCH
+            Qt5Gui_QCH
+        BLANK_MACROS
+            KCONFIGCORE_EXPORT
+            KCONFIGCORE_DEPRECATED_EXPORT
+            KCONFIGCORE_DEPRECATED
+            KCONFIGGUI_EXPORT
+            KCONFIGGUI_DEPRECATED_EXPORT
+            KCONFIGGUI_DEPRECATED
+        TAGFILE_INSTALL_DESTINATION ${KDE_INSTALL_QTQCHDIR}
+        QCH_INSTALL_DESTINATION ${KDE_INSTALL_QTQCHDIR}
+        COMPONENT Devel
+    )
+endif()
diff --git a/src/core/CMakeLists.txt b/src/core/CMakeLists.txt
index ed7edba1..9b7491c5 100644
--- a/src/core/CMakeLists.txt
+++ b/src/core/CMakeLists.txt
@@ -83,6 +83,9 @@ install(FILES
   DESTINATION ${KDE_INSTALL_INCLUDEDIR_KF5}/KConfigCore COMPONENT Devel
 )
 
+# make available to ecm_add_qch in parent folder
+set(KConfigCore_APIDOX_SRCS ${KConfigCore_HEADERS} PARENT_SCOPE)
+
 include(ECMGeneratePriFile)
 ecm_generate_pri_file(BASE_NAME KConfigCore LIB_NAME KF5ConfigCore DEPS "core" FILENAME_VAR PRI_FILENAME INCLUDE_INSTALL_DIR ${KDE_INSTALL_INCLUDEDIR_KF5}/KConfigCore)
 install(FILES ${PRI_FILENAME} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
diff --git a/src/gui/CMakeLists.txt b/src/gui/CMakeLists.txt
index 963cd3fd..9659326f 100644
--- a/src/gui/CMakeLists.txt
+++ b/src/gui/CMakeLists.txt
@@ -67,6 +67,9 @@ install(FILES
   DESTINATION ${KDE_INSTALL_INCLUDEDIR_KF5}/KConfigGui COMPONENT Devel
 )
 
+# make available to ecm_add_qch in parent folder
+set(KConfigGui_APIDOX_SRCS ${KConfigGui_HEADERS} PARENT_SCOPE)
+
 include(ECMGeneratePriFile)
 ecm_generate_pri_file(BASE_NAME KConfigGui LIB_NAME KF5ConfigGui DEPS "gui xml KConfigCore" FILENAME_VAR PRI_FILENAME INCLUDE_INSTALL_DIR ${KDE_INSTALL_INCLUDEDIR_KF5}/KConfigGui)
 install(FILES ${PRI_FILENAME} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})