Make QtDoc linkage optional

But issue a notice if not being used, and require it in most cases
in CI.

Author: pcolby

.github/workflows/build.yaml

@@ -129,6 +129,11 @@ jobs:
           [[ '${{ matrix.os }}' == '22.04' && '${{ matrix.cc }}' == 'clang' ]] ||
             "$RUNNER_TEMP/coverage/src/cli/dokit" --version
           "$RUNNER_TEMP/release/src/cli/dokit" --version
+      - name: Verify tagfiles were configured # except when using Ubuntu 22.04's Qt6 packages.
+        if: matrix.qt != '6' || matrix.os != '22.04'
+        run: |
+          grep -Ee 'qt(core|bluetooth)\.tags' "$RUNNER_TEMP/release/doc/public.doxy"
+          grep -Ee 'qt(core|bluetooth)\.tags' "$RUNNER_TEMP/release/doc/internal.doxy"
       - name: Test w/ coverage
         if: matrix.os != '22.04' || matrix.cc != 'clang'
         run: ctest --output-on-failure --test-dir "$RUNNER_TEMP/coverage" --verbose
@@ -352,6 +357,10 @@ jobs:
           "$RUNNER_TEMP/release/src/cli/dokit.app/Contents/MacOS/dokit" --version
           [[ '${{ matrix.os }}' == 'macos-13' && '${{ matrix.cc }}' == 'clang' ]] ||
             "$RUNNER_TEMP/coverage/src/cli/dokit.app/Contents/MacOS/dokit" --version
+      - name: Verify tagfiles were configured
+        run: |
+          grep -Ee 'qt(core|bluetooth)\.tags' "$RUNNER_TEMP/release/doc/public.doxy"
+          grep -Ee 'qt(core|bluetooth)\.tags' "$RUNNER_TEMP/release/doc/internal.doxy"
       - name: Grant Bluetooth access # Only needed for unit tests with older Qt's on newer runners.
         if: matrix.os != 'macos-13' && ( startsWith(matrix.qt, '5') || startsWith(matrix.qt, '6.2.') )
         run: >
@@ -664,6 +673,8 @@ jobs:
                 -D QT_INSTALL_DOCS=%RUNNER_WORKSPACE%\Qt\Docs\Qt-${{ matrix.qt }} ^
                 -G "${{ matrix.generator }}" -S "%GITHUB_WORKSPACE%" -B "%RUNNER_TEMP%/coverage"
           cmake --build "%RUNNER_TEMP%/coverage" --verbose
+          grep -Ee 'qt(core|bluetooth)\.tags' "%RUNNER_TEMP%/coverage/doc/public.doxy"
+          grep -Ee 'qt(core|bluetooth)\.tags' "%RUNNER_TEMP%/coverage/doc/internal.doxy"
       - name: Build w/o coverage instrumentation
         env:
           CMAKE_MESSAGE_LOG_LEVEL: VERBOSE
@@ -675,6 +686,8 @@ jobs:
                 -D QT_INSTALL_DOCS=%RUNNER_WORKSPACE%\Qt\Docs\Qt-${{ matrix.qt }} ^
                 -G "${{ matrix.generator }}" -S "%GITHUB_WORKSPACE%" -B "%RUNNER_TEMP%/release"
           cmake --build "%RUNNER_TEMP%/release" --verbose
+          grep -Ee 'qt(core|bluetooth)\.tags' "%RUNNER_TEMP%/release/doc/public.doxy"
+          grep -Ee 'qt(core|bluetooth)\.tags' "%RUNNER_TEMP%/release/doc/internal.doxy"
       - name: Capture build-output variables
         id: post-build
         shell: bash

.github/workflows/docs.yaml

@@ -31,6 +31,8 @@ jobs:
         run: |
           cmake -D "DOXYGEN_EXECUTABLE=$RUNNER_TEMP/doxygen-${DOXYGEN_VERSION}/bin/doxygen" \
             -S "$GITHUB_WORKSPACE" -B "$RUNNER_TEMP"
+          grep -Ee 'qt(core|bluetooth)\.tags' "$RUNNER_TEMP/release/doc/public.doxy"
+          grep -Ee 'qt(core|bluetooth)\.tags' "$RUNNER_TEMP/release/doc/internal.doxy"
           cmake --build "$RUNNER_TEMP" --target doc doc-internal
       - name: Upload public docs
         uses: actions/upload-artifact@v4

doc/CMakeLists.txt

@@ -5,14 +5,18 @@ include(FetchContent)
 FetchContent_Declare(FindQtDocs GIT_REPOSITORY "https://github.com/pcolby/cmake-modules" GIT_TAG "v1")
 FetchContent_MakeAvailable(FindQtDocs)
 list(PREPEND CMAKE_MODULE_PATH "${findqtdocs_SOURCE_DIR}")
-find_package(QtDocs REQUIRED COMPONENTS Core Bluetooth)
+find_package(QtDocs COMPONENTS Core Bluetooth)
 
 # Include Qt doc tagfiles, if available.
-set(QT_DOCS_BASEURL "https://doc.qt.io/qt-${QT_VERSION_MAJOR}/")
-message(STATUS "Using Qt doc tagfiles ${QT_INSTALL_DOCS} => ${QT_DOCS_BASEURL}")
-set(DOX_TAGFILES "\\
-  \"${QtDocs_Core_TAGS}=${QT_DOCS_BASEURL}\" \\
-  \"${QtDocs_Bluetooth_TAGS}=${QT_DOCS_BASEURL}\" \\")
+if (QtDocs_FOUND)
+  set(QT_DOCS_BASEURL "https://doc.qt.io/qt-${QT_VERSION_MAJOR}/")
+  message(STATUS "Using Qt doc tagfiles ${QT_INSTALL_DOCS} => ${QT_DOCS_BASEURL}")
+  set(DOX_TAGFILES "\\
+    \"${QtDocs_Core_TAGS}=${QT_DOCS_BASEURL}\" \\
+    \"${QtDocs_Bluetooth_TAGS}=${QT_DOCS_BASEURL}\" \\")
+else()
+  message(NOTICE "QtDocs not found. Project docs will be built without external links to Qt documentation.")
+endif()
 
 find_package(Doxygen)
 if (DOXYGEN_FOUND)