CMake: Cleanup documentation building code

Move conditions on whether documentation should be built inside the
doc project, rather than outside.

Look for qdoc and qhelpgenerator both in PATH and via
find_package(Qt6Tools) calls.

Add sanity checks that the various tools used in the
add_custom_command calls are actually available.
Show a warning or error when they are not available,
depending on combination of whether it's a standalone doc
build or part of the overall shiboken/python build.

Set DOC_OUTPUT_FORMAT to html by default if it's not specified.

Clean up some of the warning messages.

Make sure to check the result of running execute_process on the
snippets tool.

Task-number: PYSIDE-1718
Change-Id: I2969d7a40961881ad0f91d7142b29a7f4130f3b7
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
(cherry picked from commit 39f47bc8f61e8986a729a153cba619761bacc280)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

4 files changed, 130 insertions, 37 deletions

diff --git a/sources/pyside6/CMakeLists.txt b/sources/pyside6/CMakeLists.txt
index 233880997..c24de1b76 100644
--- a/sources/pyside6/CMakeLists.txt
+++ b/sources/pyside6/CMakeLists.txt
@@ -20,17 +20,4 @@ if(BUILD_TESTS)
     add_subdirectory(tests)
 endif()
 
-if(QT_SRC_DIR AND SPHINX_BUILD AND DOT_EXEC AND NOT SKIP_DOCS)
-    add_subdirectory(doc)
-else()
-    set(DOCS_TARGET_DISABLED_MESSAGE "apidoc generation targets disabled.")
-    if(NOT QT_SRC_DIR)
-        message(STATUS "QT_SRC_DIR variable not set, ${DOCS_TARGET_DISABLED_MESSAGE}")
-    elseif(NOT SPHINX_BUILD)
-        message(STATUS "sphinx-build command not found, ${DOCS_TARGET_DISABLED_MESSAGE}")
-    elseif(NOT DOT_EXEC)
-        message(STATUS "graphviz not found, ${DOCS_TARGET_DISABLED_MESSAGE}")
-    else()
-        message(STATUS "Unknown issue occurred, ${DOCS_TARGET_DISABLED_MESSAGE}")
-    endif()
-endif()
+add_subdirectory(doc)
diff --git a/sources/pyside6/cmake/PySideSetup.cmake b/sources/pyside6/cmake/PySideSetup.cmake
index d4840a4d8..7026385f2 100644
--- a/sources/pyside6/cmake/PySideSetup.cmake
+++ b/sources/pyside6/cmake/PySideSetup.cmake
@@ -230,8 +230,5 @@ if(SANITIZE_ADDRESS AND NOT MSVC)
     setup_sanitize_address()
 endif()
 
-find_program(SPHINX_BUILD sphinx-build)
-find_program(DOT_EXEC dot)
-
 find_package(Qt${QT_MAJOR_VERSION}Designer)
 
diff --git a/sources/pyside6/doc/CMakeLists.txt b/sources/pyside6/doc/CMakeLists.txt
index b36c1828f..a7639b8e6 100644
--- a/sources/pyside6/doc/CMakeLists.txt
+++ b/sources/pyside6/doc/CMakeLists.txt
@@ -3,6 +3,72 @@ cmake_policy(VERSION 3.16)
 
 project(doc)
 
+find_program(SPHINX_BUILD sphinx-build)
+
+# graphviz dot appears to be used by sphinx and not by CMake directly. This is just found to check
+# if it exists.
+find_program(DOT_EXEC dot)
+
+# Lookup for qdoc in multiple sources: cache var, PATH or CMake package.
+set(qdoc_binary "")
+find_program(QDOC_EXECUTABLE qdoc DOC "Path to qdoc binary.")
+if(QDOC_EXECUTABLE)
+    set(qdoc_binary "${QDOC_EXECUTABLE}")
+else()
+    find_package(Qt6 QUIET COMPONENTS Tools)
+    if(TARGET Qt6::qdoc)
+        set(qdoc_binary "$<TARGET_FILE:Qt6::qdoc>")
+    endif()
+endif()
+
+# Lookup for qhelpgenerator in multiple sources: cache var, PATH or CMake package.
+set(qhelpgenerator_binary "")
+find_program(QHELPGENERATOR_EXECUTABLE qhelpgenerator DOC "Path to qhelpgenerator binary.")
+if(QHELPGENERATOR_EXECUTABLE)
+    set(qhelpgenerator_binary "${QHELPGENERATOR_EXECUTABLE}")
+else()
+    find_package(Qt6 QUIET COMPONENTS Tools)
+    if(TARGET Qt6::qhelpgenerator)
+        set(qhelpgenerator_binary "$<TARGET_FILE:Qt6::qhelpgenerator>")
+    endif()
+endif()
+
+# When the doc project is built as part of the pyside project, we show informational message
+# and return early if requirements are not met.
+if(NOT CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+    if(QT_SRC_DIR AND SPHINX_BUILD AND DOT_EXEC AND NOT SKIP_DOCS)
+        # All requirements met, proceed.
+    else()
+        set(reasons "")
+        if(NOT QT_SRC_DIR)
+            list(APPEND reasons "    QT_SRC_DIR variable not set\n")
+        endif()
+        if(NOT SPHINX_BUILD)
+            list(APPEND reasons "    sphinx-build command not found\n")
+        endif()
+        if(NOT DOT_EXEC)
+            list(APPEND reasons "    graphviz not found\n")
+        endif()
+        if(SKIP_DOCS)
+            list(APPEND reasons "    SKIP_DOCS was set to TRUE\n")
+        endif()
+        message(STATUS "apidoc generation targets disabled due to the following reasons:\n"
+                ${reasons})
+        return()
+    endif()
+else()
+    # We are building the docs as a standalone project, likely via setup.py build_rst_docs
+    # command. Perform stricter sanity checks.
+    if(NOT SPHINX_BUILD)
+        message(FATAL_ERROR "sphinx-build command not found. Please set the SPHINX_BUILD variable.")
+    endif()
+endif()
+
+# Generate html by default.
+if(NOT DOC_OUTPUT_FORMAT)
+    set(DOC_OUTPUT_FORMAT "html")
+endif()
+
 if (WIN32)
     set(PATH_SEP "\;")
 else()
@@ -36,9 +102,12 @@ if (FULLDOCSBUILD)
     execute_process(COMMAND ${PYTHON_EXECUTABLE} ${SNIPPETS_TOOL}
         --qt ${QT_SRC_DIR}/.. --pyside ${PYSIDE_ROOT} -w
         WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
-        ERROR_VARIABLE SNIPPETS_ERROR)
-    if (SNIPPETS_ERROR)
-        message(FATAL_ERROR "The 'snippets_translate' tool failed: ${SNIPPETS_ERROR}")
+        ERROR_VARIABLE SNIPPETS_ERROR
+        RESULT_VARIABLE SNIPPETS_RESULT)
+    # SNIPPETS_ERROR might be empty and SNIPPET_RESULT might contain "permission denied"
+    if (SNIPPETS_ERROR OR SNIPPETS_RESULT)
+        message(FATAL_ERROR
+                "The 'snippets_translate' tool failed: ${SNIPPETS_ERROR} ${SNIPPET_RESULT}")
     endif()
 endif()
 
@@ -122,6 +191,13 @@ if (FULLDOCSBUILD)
 
     set(QDOC_TYPESYSTEM_PATH "${pyside6_SOURCE_DIR}${PATH_SEP}${pyside6_BINARY_DIR}")
 
+    if(NOT qdoc_binary)
+        message(FATAL_ERROR
+                "No qdoc binary was found which full documentation generation requires. "
+                "Please either add qdoc to PATH or specify the QDOC_EXECUTABLE variable."
+        )
+    endif()
+
     add_custom_target(qdoc DEPENDS "${DOC_DATA_DIR}/webxml/qtcore-index.webxml")
 
     add_custom_command(OUTPUT "${DOC_DATA_DIR}/webxml/qtcore-index.webxml"
@@ -130,7 +206,8 @@ if (FULLDOCSBUILD)
                        QT_VERSION=${QT_VERSION_MAJOR}.${QT_VERSION_MINOR}.${QT_VERSION_PATCH}
                        QT_VER=${QT_VERSION_MAJOR}.${QT_VERSION_MINOR}
                        QT_VERSION_TAG=${QT_VERSION_MAJOR}.${QT_VERSION_MINOR}.${QT_VERSION_PATCH}
-                       qdoc pyside.qdocconf -single-exec -installdir ${DOC_DATA_DIR} -outputdir ${DOC_DATA_DIR}
+                       "${qdoc_binary}" pyside.qdocconf -single-exec
+                           -installdir ${DOC_DATA_DIR} -outputdir ${DOC_DATA_DIR}
                        COMMENT "Running qdoc against Qt source code...")
 endif()
 
@@ -171,12 +248,19 @@ if(DOC_OUTPUT_FORMAT STREQUAL "html")
             COMMENT "Copying Shiboken docs..."
             VERBATIM)
 else()
-    file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/html/PySide.qhp QHP_FILE)
-    add_custom_command(TARGET apidoc POST_BUILD
-            COMMAND ${PYTHON_EXECUTABLE} py_script.py
-            COMMAND qhelpgenerator ${QHP_FILE}
-            COMMENT "Generating QCH from a QHP file..."
-            VERBATIM)
+    if(qhelpgenerator_binary)
+        message(STATUS "qhelpgenerator - found")
+
+        file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/html/PySide.qhp QHP_FILE)
+        add_custom_command(TARGET apidoc POST_BUILD
+                COMMAND ${PYTHON_EXECUTABLE} py_script.py
+                COMMAND "${qhelpgenerator_binary}" ${QHP_FILE}
+                COMMENT "Generating QCH from a QHP file..."
+                VERBATIM
+        )
+    else()
+        message(WARNING "qhelpgenerator - not found! qch generation disabled")
+    endif()
 endif()
 
 # create conf.py based on conf.py.in
diff --git a/sources/shiboken6/doc/CMakeLists.txt b/sources/shiboken6/doc/CMakeLists.txt
index 8d78eb400..7be47363b 100644
--- a/sources/shiboken6/doc/CMakeLists.txt
+++ b/sources/shiboken6/doc/CMakeLists.txt
@@ -5,14 +5,31 @@ if(FULLDOCSBUILD EQUAL 0)
 endif()
 find_program(SPHINX sphinx-build DOC "Path to sphinx-build binary.")
 
-if (SPHINX)
+# Lookup for qhelpgenerator in multiple sources: cache var, PATH or CMake package.
+set(qhelpgenerator_binary "")
+find_program(QHELPGENERATOR_EXECUTABLE qhelpgenerator DOC "Path to qhelpgenerator binary.")
+if(QHELPGENERATOR_EXECUTABLE)
+    set(qhelpgenerator_binary "${QHELPGENERATOR_EXECUTABLE}")
+else()
+    find_package(Qt6 QUIET COMPONENTS Tools)
+    if(TARGET Qt6::qhelpgenerator)
+        set(qhelpgenerator_binary "$<TARGET_FILE:Qt6::qhelpgenerator>")
+    endif()
+endif()
+
+# Generate html by default.
+if(NOT DOC_OUTPUT_FORMAT)
+    set(DOC_OUTPUT_FORMAT "html")
+endif()
+
+if(SPHINX)
     message(STATUS "sphinx-build - found")
     configure_file(conf.py.in conf.py @ONLY)
     # conditional tag for sphinx build
     #string(JOIN "_" SPHINX_TAG ${DOC_OUTPUT_FORMAT} "format")
     add_custom_target(doc
         COMMAND ${SPHINX} -b ${DOC_OUTPUT_FORMAT} -c . ${CMAKE_CURRENT_SOURCE_DIR} html
-        COMMENT "Generating HTMLs..."
+        COMMENT "Generating shiboken documentation HTML files"
         VERBATIM)
     # Python script that will be called to update the QHP
     set(py_cmd "
@@ -34,17 +51,25 @@ except:
     file(GENERATE OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/py_script.py
         CONTENT ${py_cmd})
 
-    # create a custom command to generate QCH
+    # Attach a POST_BUILD step to the 'doc' custom target to generate a QCH file.
     if(DOC_OUTPUT_FORMAT STREQUAL "qthelp")
-        file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/html/Shiboken.qhp QHP_FILE)
-        add_custom_command(TARGET doc POST_BUILD
-            COMMAND ${PYTHON_EXECUTABLE} py_script.py # ${CMAKE_CURRENT_BINARY_DIR}/html/Shiboken.qhp
-            COMMAND qhelpgenerator ${QHP_FILE}
-            COMMENT "Genereting QCH based on the QHP..."
-            VERBATIM)
+        if(qhelpgenerator_binary)
+            message(STATUS "qhelpgenerator - found")
+
+            file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/html/Shiboken.qhp QHP_FILE)
+            add_custom_command(TARGET doc POST_BUILD
+                COMMAND ${PYTHON_EXECUTABLE} py_script.py # ${CMAKE_CURRENT_BINARY_DIR}/html/Shiboken.qhp
+                COMMAND "${qhelpgenerator_binary}" ${QHP_FILE}
+                COMMENT "Generating shiboken documentation QCH files based on the QHP files"
+                VERBATIM)
+        else()
+            message(WARNING "qhelpgenerator - not found! qch generation disabled")
+        endif()
     endif()
 else()
-    message(WARNING "sphinx-build - not found! doc target disabled")
+    if(NOT SPHINX)
+        message(WARNING "sphinx-build - not found! doc target disabled")
+    endif()
     if (WIN32)
         # if jom is used and we have no sphinx, then jom will crash.
         # so for windows, we always create a doc target (until jom gets fixed...)