QtDocsHelpers.cmake

# Copyright (C) 2022 The Qt Company Ltd.
# SPDX-License-Identifier: BSD-3-Clause

# This function adds a dependency between a doc-generating target like 'generate_docs_Gui'
# and the necessary tool target like 'qdoc'.
#
# If the target is not yet existing, save the dependency connection in a global property.
# The dependency is then added near the end of the top-level build after all subdirectories have
# been handled.
function(qt_internal_add_doc_tool_dependency doc_target tool_name)
    qt_get_tool_target_name(tool_target ${tool_name})
    if(TARGET ${tool_target})
        add_dependencies(${doc_target} ${tool_target})
    else()
        qt_internal_defer_dependency(${doc_target} ${tool_target})
    endif()
endfunction()

function(qt_internal_add_docs)
    if(NOT QT_BUILD_DOCS)
        return()
    endif()

    if(${ARGC} EQUAL 1)
        # Function called from old generated CMakeLists.txt that was missing the target parameter
        return()
    endif()
    set(error_msg "qt_add_docs called with wrong number of arguments. ")
    list(APPEND error_msg
        "Should be qt_add_docs\(target_name qdocconf "
        "\[INDEX_DIRECTORIES EXTRA_INDEX_DIRS_LIST_TO_ENABLE_QDOC_RESOLVE_LINKS\]\)")
    if(NOT ${ARGC} GREATER_EQUAL 2)
        message(FATAL_ERROR ${error_msg})
        return()
    endif()

    set(target ${ARGV0})
    set(doc_project ${ARGV1})
    set(qdoc_extra_args "")
    # Check if there are more than 2 arguments and pass them
    # as extra --indexdir arguments to qdoc in prepare and
    # generate phases.
    if (${ARGC} GREATER 2)
        # The INDEX_DIRECTORIES key should enable passing a list of index
        # directories as extra command-line arguments to qdoc.
        set(qdocExtraArgs "INDEX_DIRECTORIES;DEFINES")
        cmake_parse_arguments(PARSE_ARGV 2 arg "" "" "${qdocExtraArgs}")
        if(arg_UNPARSED_ARGUMENTS)
            message(FATAL_ERROR ${error_msg})
            return()
        endif()
        if(arg_INDEX_DIRECTORIES)
            foreach(index_directory ${arg_INDEX_DIRECTORIES})
                list(APPEND qdoc_extra_args "--indexdir" ${index_directory})
            endforeach()
        endif()
    endif()


    # If a target is not built (which can happen for tools when crosscompiling), we shouldn't try
    # to generate docs.
    if(NOT TARGET "${target}")
        return()
    endif()

    set(tool_dependencies_enabled TRUE)
    if(NOT "${QT_HOST_PATH}" STREQUAL "")
        set(tool_dependencies_enabled FALSE)
        set(doc_tools_bin "${QT_HOST_PATH}/${QT${PROJECT_VERSION_MAJOR}_HOST_INFO_BINDIR}")
        set(doc_tools_libexec "${QT_HOST_PATH}/${QT${PROJECT_VERSION_MAJOR}_HOST_INFO_LIBEXECDIR}")
    elseif(NOT "${QT_OPTIONAL_TOOLS_PATH}" STREQUAL "")
        set(tool_dependencies_enabled FALSE)
        set(doc_tools_bin "${QT_OPTIONAL_TOOLS_PATH}/${INSTALL_BINDIR}")
        set(doc_tools_libexec "${QT_OPTIONAL_TOOLS_PATH}/${INSTALL_LIBEXECDIR}")
    elseif(QT_SUPERBUILD)
        set(doc_tools_bin "${QtBase_BINARY_DIR}/${INSTALL_BINDIR}")
        set(doc_tools_libexec "${QtBase_BINARY_DIR}/${INSTALL_LIBEXECDIR}")
    else()
        set(doc_tools_bin "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_BINDIR}")
        set(doc_tools_libexec "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_LIBEXECDIR}")
    endif()

    if(CMAKE_HOST_WIN32)
        set(executable_suffix ".exe")
    else()
        set(executable_suffix "")
    endif()

    set(qdoc_bin "${doc_tools_bin}/qdoc${executable_suffix}")
    set(qtattributionsscanner_bin "${doc_tools_libexec}/qtattributionsscanner${executable_suffix}")
    set(qhelpgenerator_bin "${doc_tools_libexec}/qhelpgenerator${executable_suffix}")

    get_target_property(target_type ${target} TYPE)
    if (NOT target_type STREQUAL "INTERFACE_LIBRARY")
        get_target_property(target_bin_dir ${target} BINARY_DIR)
        get_target_property(target_source_dir ${target} SOURCE_DIR)
    else()
        set(target_bin_dir ${CMAKE_CURRENT_BINARY_DIR})
        set(target_source_dir ${CMAKE_CURRENT_SOURCE_DIR})
    endif()
    set(doc_output_dir "${target_bin_dir}/.doc")

    # Generate include dir list
    set(target_include_dirs_file "${doc_output_dir}/$<CONFIG>/includes.txt")


    set(prop_prefix "")
    if(target_type STREQUAL "INTERFACE_LIBRARY")
        set(prop_prefix "INTERFACE_")
    endif()
    set(include_path_prop "${prop_prefix}INCLUDE_DIRECTORIES")

    set(include_paths_property "$<TARGET_PROPERTY:${target},${include_path_prop}>")
    if (NOT target_type STREQUAL "UTILITY")
        file(GENERATE
            OUTPUT ${target_include_dirs_file}
            CONTENT "$<$<BOOL:${include_paths_property}>:-I$<JOIN:${include_paths_property},\n-I>>"
        )
        set(include_path_args "@${target_include_dirs_file}")
    else()
        set(include_path_args "")
    endif()

    get_filename_component(doc_target "${doc_project}" NAME_WLE)
    if (QT_WILL_INSTALL)
        set(qdoc_output_dir "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}/${doc_target}")
        set(qdoc_qch_output_dir "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}")
        set(index_dir "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}")
    else()
        set(qdoc_output_dir "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_DOCDIR}/${doc_target}")
        set(qdoc_qch_output_dir "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_DOCDIR}")
        set(index_dir "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_DOCDIR}")
    endif()

    # qtattributionsscanner
    add_custom_target(qattributionsscanner_${target}
        COMMAND ${qtattributionsscanner_bin}
        ${PROJECT_SOURCE_DIR}
        --basedir "${PROJECT_SOURCE_DIR}/.."
        --filter "QDocModule=${doc_target}"
        -o "${target_bin_dir}/codeattributions.qdoc"
    )

    # prepare docs target
    set(prepare_qdoc_args
        -outputdir "${qdoc_output_dir}"
        "${target_source_dir}/${doc_project}"
        -prepare
        -indexdir "${index_dir}"
        -no-link-errors
        "${include_path_args}"
    )
    if(NOT QT_BUILD_ONLINE_DOCS)
        list(PREPEND prepare_qdoc_args
            -installdir "${QT_INSTALL_DIR}/${INSTALL_DOCDIR}"
            ${qdoc_extra_args}
        )
    endif()

    if(DEFINED ENV{QT_INSTALL_DOCS})
        if(NOT EXISTS "$ENV{QT_INSTALL_DOCS}")
            message(FATAL_ERROR
                "Environment variable QT_INSTALL_DOCS points to a directory which does not exist:\n"
                "$ENV{QT_INSTALL_DOCS}")
        endif()
        set(qt_install_docs_env "$ENV{QT_INSTALL_DOCS}")
    elseif(QT_SUPERBUILD OR "${PROJECT_NAME}" STREQUAL "QtBase")
        set(qt_install_docs_env "${QtBase_BINARY_DIR}/${INSTALL_DOCDIR}")
    else()
        set(qt_install_docs_env "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_DOCDIR}")
    endif()

    set(qdoc_env_args
        "QT_INSTALL_DOCS=\"${qt_install_docs_env}\""
        "QT_VERSION=${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}"
        "QT_VER=${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}"
        "QT_VERSION_TAG=${PROJECT_VERSION_MAJOR}${PROJECT_VERSION_MINOR}${PROJECT_VERSION_PATCH}"
        "BUILDDIR=${target_bin_dir}"
    )
    if(arg_DEFINES)
        foreach(define ${arg_DEFINES})
            list(APPEND qdoc_env_args "${define}")
        endforeach()
    endif()

    add_custom_target(prepare_docs_${target}
        COMMAND ${CMAKE_COMMAND} -E env ${qdoc_env_args}
        ${qdoc_bin}
        ${prepare_qdoc_args}
    )

    add_dependencies(prepare_docs_${target} qattributionsscanner_${target})
    if(NOT TARGET sync_all_public_headers)
        add_custom_target(sync_all_public_headers)
    endif()
    add_dependencies(prepare_docs_${target} sync_all_public_headers)

    # generate docs target
    set(generate_qdoc_args
        -outputdir "${qdoc_output_dir}"
        "${target_source_dir}/${doc_project}"
        -generate
        -indexdir "${index_dir}"
        "${include_path_args}"
    )
    if(NOT QT_BUILD_ONLINE_DOCS)
        list(PREPEND generate_qdoc_args
            -installdir "${QT_INSTALL_DIR}/${INSTALL_DOCDIR}"
            ${qdoc_extra_args}
        )
    endif()

    foreach(target_prefix generate_top_level_docs generate_repo_docs generate_docs)
        set(depends_arg "")
        if(tool_dependencies_enabled)
            set(depends_arg DEPENDS ${qdoc_bin})
        endif()
        add_custom_target(${target_prefix}_${target}
            ${depends_arg}
            COMMAND ${CMAKE_COMMAND} -E env ${qdoc_env_args} ${qdoc_bin} ${generate_qdoc_args})
    endforeach()

    add_dependencies(generate_docs_${target} prepare_docs_${target})
    add_dependencies(generate_repo_docs_${target} ${qt_docs_prepare_target_name})
    add_dependencies(generate_top_level_docs_${target} prepare_docs)
    add_dependencies(generate_docs generate_top_level_docs_${target})

    # html docs target
    add_custom_target(html_docs_${target})
    add_dependencies(html_docs_${target} generate_docs_${target})

    # generate .qch
    set(qch_file_name ${doc_target}.qch)
    set(qch_file_path ${qdoc_qch_output_dir}/${qch_file_name})

    foreach(target_prefix qch_top_level_docs qch_repo_docs qch_docs)
        set(depends_arg "")
        if(tool_dependencies_enabled)
            set(depends_arg DEPENDS ${qhelpgenerator_bin})
        endif()
        add_custom_target(${target_prefix}_${target}
            ${depends_arg}
            COMMAND ${qhelpgenerator_bin}
            "${qdoc_output_dir}/${doc_target}.qhp"
            -o "${qch_file_path}"
        )
    endforeach()
    add_dependencies(qch_docs_${target} generate_docs_${target})
    add_dependencies(qch_repo_docs_${target} ${qt_docs_generate_target_name})
    add_dependencies(qch_top_level_docs_${target} generate_docs)
    add_dependencies(qch_docs qch_top_level_docs_${target})

    if (QT_WILL_INSTALL)
        install(DIRECTORY "${qdoc_output_dir}/"
                DESTINATION "${INSTALL_DOCDIR}/${doc_target}"
                COMPONENT _install_html_docs_${target}
                EXCLUDE_FROM_ALL
        )

        add_custom_target(install_html_docs_${target}
            COMMAND ${CMAKE_COMMAND}
            --install "${CMAKE_BINARY_DIR}"
            --component _install_html_docs_${target}
            COMMENT "Installing html docs for target ${target}"
        )

        install(FILES "${qch_file_path}"
                DESTINATION "${INSTALL_DOCDIR}"
                COMPONENT _install_qch_docs_${target}
                EXCLUDE_FROM_ALL
        )

        add_custom_target(install_qch_docs_${target}
            COMMAND ${CMAKE_COMMAND}
            --install "${CMAKE_BINARY_DIR}"
            --component _install_qch_docs_${target}
            COMMENT "Installing qch docs for target ${target}"
        )

    else()
        # Don't need to do anything when not installing
        add_custom_target(install_html_docs_${target})
        add_custom_target(install_qch_docs_${target})
    endif()

    add_custom_target(install_docs_${target})
    add_dependencies(install_docs_${target} install_html_docs_${target} install_qch_docs_${target})

    add_custom_target(docs_${target})
    add_dependencies(docs_${target} html_docs_${target})
    add_dependencies(docs_${target} qch_docs_${target})

    add_dependencies(${qt_docs_prepare_target_name} prepare_docs_${target})
    add_dependencies(${qt_docs_generate_target_name} generate_repo_docs_${target})
    add_dependencies(${qt_docs_qch_target_name} qch_repo_docs_${target})
    add_dependencies(${qt_docs_install_html_target_name} install_html_docs_${target})
    add_dependencies(${qt_docs_install_qch_target_name} install_qch_docs_${target})

    # Make sure that the necessary tools are built when running,
    # for example 'cmake --build . --target generate_docs'.
    if(tool_dependencies_enabled)
        qt_internal_add_doc_tool_dependency(qattributionsscanner_${target} qtattributionsscanner)
        qt_internal_add_doc_tool_dependency(prepare_docs_${target} qdoc)
        qt_internal_add_doc_tool_dependency(qch_docs_${target} qhelpgenerator)
    endif()
endfunction()