From ff7850ec3096a0090d4bd4bfe25e2cf7f0bccd05 Mon Sep 17 00:00:00 2001 From: Alexandru Croitor Date: Wed, 27 Oct 2021 10:33:51 +0200 Subject: 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 Reviewed-by: Friedemann Kleint Reviewed-by: Cristian Maureira-Fredes (cherry picked from commit 39f47bc8f61e8986a729a153cba619761bacc280) Reviewed-by: Qt Cherry-pick Bot --- sources/pyside6/CMakeLists.txt | 15 +---- sources/pyside6/cmake/PySideSetup.cmake | 3 - sources/pyside6/doc/CMakeLists.txt | 104 +++++++++++++++++++++++++++++--- sources/shiboken6/doc/CMakeLists.txt | 45 +++++++++++--- 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 "$") + 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 "$") + 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 "$") + 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...) -- cgit v1.2.3