Docs: Make QDOC_INDEX_DIR optional

If the Qt documentation index files are not available (which they may not be, since some distro installs of Qt6 don't package the documentation), the GammaRay manual can still be built. All of its links to the system docs will be broken, but that doesn't render it unusable. Allow building the documentation even without access to the .index files for the system docs, but print a message about broken links.
KDAB · Nov 18, 2023 · ddbe652 · ddbe652
1 parent f937357
commit ddbe652
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 11 deletions.
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -46,7 +46,7 @@ if(NOT DEFINED QDOC_TEMPLATE_DIR)
 endif()
 
 if(NOT DEFINED QDOC_INDEX_DIR)
-    # compute the qdoc index dir from where qtcore.index is found
+    # try to compute the qdoc index dir from where qtcore.index is found
     find_file(QDOC_INDEX qtcore.index HINTS ${QT_INSTALL_DOCS}/qtcore ${QT_INSTALL_DATA}/doc/qtcore)
     if(QDOC_INDEX)
         get_filename_component(QDOC_INDEX_DIR ${QDOC_INDEX} DIRECTORY)
@@ -57,7 +57,6 @@ endif()
 if(NOT QDOC_EXECUTABLE
    OR NOT QHELPGEN_EXECUTABLE
    OR NOT QDOC_TEMPLATE_DIR
-   OR NOT QDOC_INDEX_DIR
    OR NOT QTATTRIBUTIONSSCANNER_EXECUTABLE
 )
     # Expand imported target data for status reporting
@@ -82,6 +81,9 @@ if(NOT QDOC_EXECUTABLE
     set(GAMMARAY_USER_MANUAL_BUILD False)
 else()
     set(GAMMARAY_USER_MANUAL_BUILD True)
+    if(NOT QDOC_INDEX_DIR)
+        message(STATUS "Couldn't find index dir, manual won't link to system documentation")
+    endif()
 endif()
 
 add_feature_info(

diff --git a/docs/manual/CMakeLists.txt b/docs/manual/CMakeLists.txt
@@ -19,6 +19,12 @@ macro(qt_build_doc _qdocconf_name)
         COMMENT "Generate codecontrbutions.qdoc using qtattributescanner"
     )
 
+    # Point to the qt documentation index files, if discovered
+    set(_qdoc_index_args)
+    if(QDOC_INDEX_DIR)
+        set(_qdoc_index_args --indexdir ${QDOC_INDEX_DIR})
+    endif()
+
     # offline docs
     # run qdoc to get qhp file
     set(_qdoc_output_dir ${CMAKE_CURRENT_BINARY_DIR}/${_qdocconf_name})
@@ -30,9 +36,8 @@ macro(qt_build_doc _qdocconf_name)
         OUTPUT ${_qdoc_output_dir}/${_qdocconf_name}.qhp
         COMMAND
             ${CMAKE_COMMAND} -E env QT_INSTALL_DOCS=${QDOC_TEMPLATE_DIR} QT_VERSION_TAG=${GAMMARAY_PLUGIN_VERSION}
-            QT_VERSION=${GAMMARAY_VERSION} BUILDDIR=${CMAKE_CURRENT_BINARY_DIR} ${QDOC_EXECUTABLE} --indexdir
-            ${QDOC_INDEX_DIR} --outputdir ${_qdoc_output_dir}
-            ${CMAKE_CURRENT_SOURCE_DIR}/${_qdocconf_name}-offline.qdocconf
+            QT_VERSION=${GAMMARAY_VERSION} BUILDDIR=${CMAKE_CURRENT_BINARY_DIR} ${QDOC_EXECUTABLE} ${_qdoc_index_args}
+            --outputdir ${_qdoc_output_dir} ${CMAKE_CURRENT_SOURCE_DIR}/${_qdocconf_name}-offline.qdocconf
         DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${_qdocconf_name}-offline.qdocconf ${_qdoc_srcs} ${_qdoc_imgs}
         COMMENT "Generate the offline manual using qdoc"
     )
@@ -61,9 +66,8 @@ macro(qt_build_doc _qdocconf_name)
         OUTPUT ${_qdoc_output_dir}/index.html
         COMMAND
             ${CMAKE_COMMAND} -E env QT_INSTALL_DOCS=${QDOC_TEMPLATE_DIR} QT_VERSION_TAG=${GAMMARAY_PLUGIN_VERSION}
-            QT_VERSION=${GAMMARAY_VERSION} BUILDDIR=${CMAKE_CURRENT_BINARY_DIR} ${QDOC_EXECUTABLE} --indexdir
-            ${QDOC_INDEX_DIR} --outputdir ${_qdoc_output_dir}
-            ${CMAKE_CURRENT_SOURCE_DIR}/${_qdocconf_name}-online.qdocconf
+            QT_VERSION=${GAMMARAY_VERSION} BUILDDIR=${CMAKE_CURRENT_BINARY_DIR} ${QDOC_EXECUTABLE} ${_qdoc_index_args}
+            --outputdir ${_qdoc_output_dir} ${CMAKE_CURRENT_SOURCE_DIR}/${_qdocconf_name}-online.qdocconf
         DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${_qdocconf_name}-online.qdocconf ${_qdoc_srcs} ${_qdoc_imgs}
                 ${_qdoc_styles}
         COMMENT "Generate the Qt-branded online manual using qdoc"
@@ -79,9 +83,8 @@ macro(qt_build_doc _qdocconf_name)
         OUTPUT ${_qdoc_output_dir}/index.html
         COMMAND
             ${CMAKE_COMMAND} -E env QT_INSTALL_DOCS=${QDOC_TEMPLATE_DIR} QT_VERSION_TAG=${GAMMARAY_PLUGIN_VERSION}
-            QT_VERSION=${GAMMARAY_VERSION} BUILDDIR=${CMAKE_CURRENT_BINARY_DIR} ${QDOC_EXECUTABLE} --indexdir
-            ${QDOC_INDEX_DIR} --outputdir ${_qdoc_output_dir}
-            ${CMAKE_CURRENT_SOURCE_DIR}/${_qdocconf_name}-online-kdab.qdocconf
+            QT_VERSION=${GAMMARAY_VERSION} BUILDDIR=${CMAKE_CURRENT_BINARY_DIR} ${QDOC_EXECUTABLE} ${_qdoc_index_args}
+            --outputdir ${_qdoc_output_dir} ${CMAKE_CURRENT_SOURCE_DIR}/${_qdocconf_name}-online-kdab.qdocconf
         DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${_qdocconf_name}-online-kdab.qdocconf ${_qdoc_srcs} ${_qdoc_imgs}
                 ${_qdoc_styles}
         COMMENT "Generate the KDAB-branded online manual using qdoc"