diff options
| author | Tatiana Borisova <tatiana.borisova@qt.io> | 2025-11-26 19:04:59 +0100 |
|---|---|---|
| committer | Tatiana Borisova <tatiana.borisova@qt.io> | 2025-12-17 13:32:52 +0000 |
| commit | 16247c5c49b6bb49c85091f78f1d23ac3b975782 (patch) | |
| tree | e996c835714bba36637581f567d0471644f8f79c | |
| parent | 6c10db19c8dd2fa406a91e95c2ff29bc74c543b5 (diff) | |
Add GEN_DOXYGEN_DOCS option for qt6_add_openapi_client function6.11
- The GEN_DOXYGEN_DOCS option can be used for enabling
The documentation generation into a specified directory.
- doxygen program is required for generation. In case the
Doxygen is not installed, the option is ignored and
nothing is generated.
Task-number: QTBUG-141981
(cherry picked from commit 30e9ea4193e0e2401a84ae00685a3b0d4dfcb36d)
Change-Id: I9d05faa063c6e291302906673aa50cd7962382f1
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
Reviewed-by: Rym Bouabid <rym.bouabid@qt.io>
5 files changed, 104 insertions, 3 deletions
diff --git a/src/global/configure.cmake b/src/global/configure.cmake index b92de62..c8500f9 100644 --- a/src/global/configure.cmake +++ b/src/global/configure.cmake @@ -13,6 +13,7 @@ set(java_compiler_value "<not found>") set(golang_value "<not found>") set(maven_value "<not found>") set(openapi_generator_value "<not found>") +set(doxygen_value "<not found>") set(build_all_tests_value "no") set(zlib_value "no") @@ -23,6 +24,7 @@ set(golang_found FALSE) set(maven_found FALSE) set(openapi_generator_found FALSE) set(zlib_found FALSE) +set(doxygen_found FALSE) # Look for zlib, which is a required dependency for the soon-to-be generated OpenAPI Common # library. @@ -70,6 +72,13 @@ if(NOT QT_CONFIGURE_RUNNING) set(golang_found TRUE) endif() + # Look for doxygen, used to create documentation for the generated code + find_package(Doxygen) + if (DOXYGEN_EXECUTABLE) + set(doxygen_value "${DOXYGEN_EXECUTABLE}") + set(doxygen_found TRUE) + endif() + # We need to find the upstream OpenAPI generator in order to build the OpenApiCommon # library and to be able to generate any client library qt_find_package(WrapOpenAPIGenerator PROVIDED_TARGETS WrapOpenAPIGenerator::WrapOpenAPIGenerator) @@ -139,6 +148,7 @@ qt_configure_add_summary_section(NAME "Qt OpenAPI") qt_configure_add_summary_entry(ARGS "openapi_generator") qt_configure_add_summary_entry(ARGS "All test dependencies found" TYPE "message" MESSAGE "${build_all_tests_value}") +qt_configure_add_summary_entry(ARGS "doxygen" TYPE "message" MESSAGE "${doxygen_value}") qt_configure_end_summary_section() qt_configure_add_report_entry( @@ -194,3 +204,14 @@ if(NOT zlib_found) MESSAGE "${zlib_check_msg}" ) endif() + +if(NOT doxygen_found) + string(CONCAT doxygen_msg + "The doxygen was not found. The GEN_DOXYGEN_DOCS option of the qt6_add_openapi_client " + "function will be ignored. It means no doxygen documentation will be generated." + ) + qt_configure_add_report_entry( + TYPE WARNING + MESSAGE "${doxygen_msg}" + ) +endif() diff --git a/src/openapi/Qt6OpenApiConfigureDoxygenScript.cmake b/src/openapi/Qt6OpenApiConfigureDoxygenScript.cmake new file mode 100644 index 0000000..1241d60 --- /dev/null +++ b/src/openapi/Qt6OpenApiConfigureDoxygenScript.cmake @@ -0,0 +1,34 @@ +# Copyright (C) 2025 The Qt Company Ltd. +# SPDX-License-Identifier: BSD-3-Clause + +cmake_minimum_required(VERSION 3.21) + +if(NOT DOXYGEN_IN_FILE_PATH) + message(FATAL_ERROR "Doxyfile input file is not set") +endif() + +if(NOT DOXYGEN_OUT_FILE_PATH) + message(FATAL_ERROR "Doxyfile output file is not set") +endif() + +if(NOT INPUT_DIR) + message(FATAL_ERROR "INPUT_DIR is not set") +endif() + +if(NOT OUTPUT_DIR) + message(FATAL_ERROR "OUTPUT_DIR is not set") +endif() + +if(NOT EXCLUDE_FILE) + message(FATAL_ERROR "EXCLUDE_FILE is not set") +endif() + +set(DOXY_OUT_DIR "${OUTPUT_DIR}") +set(DOXY_IN_DIR "${INPUT_DIR}") +set(DOXY_EXCLUDE_FILE "${EXCLUDE_FILE}") + +configure_file( + "${DOXYGEN_IN_FILE_PATH}" + "${DOXYGEN_OUT_FILE_PATH}" + @ONLY +) diff --git a/src/openapi/Qt6OpenApiToolsGeneratorMacros.cmake b/src/openapi/Qt6OpenApiToolsGeneratorMacros.cmake index 9e2d413..48a5227 100644 --- a/src/openapi/Qt6OpenApiToolsGeneratorMacros.cmake +++ b/src/openapi/Qt6OpenApiToolsGeneratorMacros.cmake @@ -32,6 +32,7 @@ endfunction() function(qt6_add_openapi_client target) set(options + GENERATE_DOCUMENTATION __QT_INTERNAL_GENERATE_COMMON_LIBRARY_TARGET ) set(oneValueArgs @@ -39,6 +40,7 @@ function(qt6_add_openapi_client target) CPP_NAMESPACE CLIENT_PREFIX OUTPUT_DIRECTORY + DOCUMENTATION_OUTPUT_DIRECTORY OUTPUT_PUBLIC_HEADERS_DIR OUTPUT_PRIVATE_HEADERS_DIR ) @@ -87,6 +89,9 @@ function(qt6_add_openapi_client target) endif() file(MAKE_DIRECTORY "${arg_OUTPUT_DIRECTORY}") + if(NOT arg_DOCUMENTATION_OUTPUT_DIRECTORY) + set(arg_DOCUMENTATION_OUTPUT_DIRECTORY "${arg_OUTPUT_DIRECTORY}") + endif() set(openapi_cli_entrypoint_class "org.openapitools.codegen.OpenAPIGenerator") set(generator_name ${QT_OPENAPI_GENERATOR_NAME}) get_filename_component(openapi_generator_cli_dir @@ -175,6 +180,7 @@ function(qt6_add_openapi_client target) list(APPEND client_sources "${client_dir_path}${target_lower_case}combinedmodelsandapis.cpp") list(APPEND client_sources "${client_dir_path}${target_lower_case}exports.h") + list(APPEND client_sources "${client_dir_path}doc/Doxyfile.in") list(APPEND generating_sources ${client_sources}) endif() @@ -287,6 +293,43 @@ function(qt6_add_openapi_client target) target_sources(${target} PRIVATE ${client_sources}) endif() + # Generate Doxygen documentation for the Client. + if(arg_GENERATE_DOCUMENTATION) + # If Doxygen is not installed, then just skipping. + if(TARGET Doxygen::doxygen) + file(MAKE_DIRECTORY "${arg_DOCUMENTATION_OUTPUT_DIRECTORY}") + set(configure_doxygen_script + "${__qt_openapi_macros_module_base_dir}/Qt6OpenApiConfigureDoxygenScript.cmake") + set(MAIN_GEN_DOC_FILE + "${arg_DOCUMENTATION_OUTPUT_DIRECTORY}/doc/html/index.html") + set(DOXYGEN_FILE "${client_dir_path}doc/Doxyfile") + add_custom_command( + OUTPUT "${MAIN_GEN_DOC_FILE}" + COMMAND "${CMAKE_COMMAND}" + "-DDOXYGEN_IN_FILE_PATH=${DOXYGEN_FILE}.in" + "-DDOXYGEN_OUT_FILE_PATH=${DOXYGEN_FILE}" + "-DEXCLUDE_FILE=${client_dir_path}${target_lower_case}combinedmodelsandapis.cpp" + "-DINPUT_DIR=${client_dir_path}" + "-DOUTPUT_DIR=${arg_DOCUMENTATION_OUTPUT_DIRECTORY}/doc" + -P "${configure_doxygen_script}" + COMMAND $<TARGET_FILE:Doxygen::doxygen> "${DOXYGEN_FILE}" + ${extra_dependencies} + ${generating_sources} + COMMENT "Generating doxygen documentation for target '${target}'" + VERBATIM + COMMAND_EXPAND_LISTS + ) + add_custom_target(${target}_openapi_docs ALL + DEPENDS "${MAIN_GEN_DOC_FILE}" + ) + else() + message(WARNING "Could not find doxygen to generate documentation. " + "Either install it or make sure it's added to PATH and then call " + "find_package(Doxygen) in your project." + "Skipping documentation generation.") + endif() + endif() + if(arg_OUTPUT_PUBLIC_HEADERS_DIR OR arg_OUTPUT_PRIVATE_HEADERS_DIR) set(client_public_headers_dir "${arg_OUTPUT_DIRECTORY}/${client_dir}_public_headers") set(client_private_headers_dir "${arg_OUTPUT_DIRECTORY}/${client_dir}_private_headers") diff --git a/src/tools/qtopenapi-generator/src/main/resources/cpp-qt6-client/doc/Doxyfile.in.mustache b/src/tools/qtopenapi-generator/src/main/resources/cpp-qt6-client/doc/Doxyfile.in.mustache index 0c8f553..443a07d 100644 --- a/src/tools/qtopenapi-generator/src/main/resources/cpp-qt6-client/doc/Doxyfile.in.mustache +++ b/src/tools/qtopenapi-generator/src/main/resources/cpp-qt6-client/doc/Doxyfile.in.mustache @@ -68,7 +68,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = "./doc" +OUTPUT_DIRECTORY = @DOXY_OUT_DIR@ # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 # sub-directories (in 2 levels) under the output directory of each output format @@ -943,7 +943,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = "" +INPUT = @DOXY_IN_DIR@ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -1047,7 +1047,7 @@ RECURSIVE = NO # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = {{prefix}}CombinedModelsAndAPIs.cpp +EXCLUDE = @DOXY_EXCLUDE_FILE@ # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded diff --git a/tests/auto/compression/client/tst_compression/CMakeLists.txt b/tests/auto/compression/client/tst_compression/CMakeLists.txt index f195a95..fb828c3 100644 --- a/tests/auto/compression/client/tst_compression/CMakeLists.txt +++ b/tests/auto/compression/client/tst_compression/CMakeLists.txt @@ -22,6 +22,8 @@ else() endif() endif() +find_package(Doxygen) + qt_internal_add_test(cpp-qt-compression SOURCES tst_compression.cpp @@ -35,6 +37,7 @@ qt_add_library(CompressionClient) qt6_add_openapi_client(CompressionClient SPEC_FILE ${CMAKE_CURRENT_SOURCE_DIR}/compression.yaml + GENERATE_DOCUMENTATION ) # target_compile_definitions(cpp-qt-compression |