forked from qt-creator/qt-creator
0acce09457
It requires us to pass a whole bunch of include paths manually, including Qt include paths. Extracts a stripped down list of include paths from all the plugin and library targets that we know of. On macOS, also gets Qt's framework path derived from the QtCore location. Since these can contain generator expressions, we have to write them to a file (so the expressions are resolved). We pass this file with qdoc options with the hidden "@" command line feature of qdoc. Task-number: QTCREATORBUG-22451 Change-Id: Ifae6960023cc6e63cd66104417dd4a16f2e491a2 Reviewed-by: Cristian Adam <cristian.adam@qt.io>
303 lines
11 KiB
CMake
303 lines
11 KiB
CMake
# Generate documentation
|
|
|
|
# Options:
|
|
option(WITH_DOCS "Build documentation" OFF)
|
|
add_feature_info("Build documentation" WITH_DOCS "")
|
|
|
|
option(WITH_ONLINE_DOCS "Build online documentation" OFF)
|
|
add_feature_info("Build online documentation" WITH_ONLINE_DOCS "")
|
|
|
|
option(BUILD_DEVELOPER_DOCS "Include developer documentation" OFF)
|
|
add_feature_info("Include developer documentation" BUILD_DEVELOPER_DOCS "")
|
|
|
|
function(_find_all_includes _ret_includes _ret_framework_paths)
|
|
set(_all_includes "${PROJECT_SOURCE_DIR}/src/plugins;${PROJECT_SOURCE_DIR}/src/libs")
|
|
foreach(_target ${__QTC_PLUGINS} ${__QTC_LIBRARIES})
|
|
if (NOT TARGET ${_target})
|
|
continue()
|
|
endif()
|
|
get_target_property(_includes ${_target} INCLUDE_DIRECTORIES)
|
|
foreach(_include ${_includes})
|
|
string(FIND "${_include}" "/src/plugins/" _in_plugins)
|
|
string(FIND "${_include}" "/src/libs/" _in_libs)
|
|
string(FIND "${_include}" "${CMAKE_BINARY_DIR}" _in_build)
|
|
if(_in_plugins LESS 0 AND _in_libs LESS 0 AND _in_build LESS 0)
|
|
list(APPEND _all_includes ${_include})
|
|
endif()
|
|
endforeach()
|
|
endforeach()
|
|
list(APPEND _all_includes ${CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES})
|
|
list(REMOVE_DUPLICATES _all_includes)
|
|
set("${_ret_includes}" "${_all_includes}" PARENT_SCOPE)
|
|
|
|
# framework path
|
|
if (APPLE)
|
|
get_target_property(_qt_target Qt5::Core LOCATION) # <fw_path>/QtCore.framework/QtCore
|
|
get_filename_component(_qt_loc "${_qt_target}" DIRECTORY)
|
|
set("${_ret_framework_paths}" "${_qt_loc}/.." PARENT_SCOPE)
|
|
endif()
|
|
endfunction()
|
|
|
|
# Find programs:
|
|
function(_doc_find_program result_var)
|
|
if (NOT TARGET Qt5::qmake)
|
|
message(FATAL_ERROR "QDoc is only available in Qt5 projects")
|
|
endif()
|
|
|
|
get_target_property(_qmake_binary Qt5::qmake IMPORTED_LOCATION)
|
|
get_filename_component(_qmake_dir "${_qmake_binary}" DIRECTORY)
|
|
find_program("_prg_${result_var}" ${ARGN} HINTS "${_qmake_dir}")
|
|
if ("_prg_${result_var}" STREQUAL "_prg_${result_var}-NOTFOUND")
|
|
set("_prg_${result_var}" "${result_var}-NOTFOUND")
|
|
message(WARNING "Could not find binary for ${result_var}")
|
|
endif()
|
|
|
|
set(${result_var} "${_prg_${result_var}}" PARENT_SCOPE)
|
|
endfunction()
|
|
|
|
function(_setup_doc_targets)
|
|
# Set up important targets:
|
|
if (NOT TARGET html_docs)
|
|
add_custom_target(html_docs COMMENT "Build HTML documentation")
|
|
endif()
|
|
if (NOT TARGET qch_docs)
|
|
add_custom_target(qch_docs COMMENT "Build QCH documentation")
|
|
endif()
|
|
if (NOT TARGET docs)
|
|
add_custom_target(docs COMMENT "Build documentation")
|
|
add_dependencies(docs html_docs qch_docs)
|
|
endif()
|
|
if (NOT TARGET install_docs)
|
|
add_custom_target(install_docs COMMENT "Install documentation")
|
|
add_dependencies(install_docs docs)
|
|
endif()
|
|
if (NOT TARGET clean_docs)
|
|
add_custom_target(clean_docs COMMENT "Clean documentation files from build directory")
|
|
endif()
|
|
endfunction()
|
|
|
|
function(_setup_qdoc_targets _qdocconf_file _retval)
|
|
cmake_parse_arguments(_arg "" "HTML_DIR;INSTALL_DIR;POSTFIX"
|
|
"INDEXES;INCLUDE_DIRECTORIES;FRAMEWORK_PATHS;ENVIRONMENT_EXPORTS" ${ARGN})
|
|
|
|
foreach(_index ${_arg_INDEXES})
|
|
list(APPEND _qdoc_index_args "-indexdir;${_index}")
|
|
endforeach()
|
|
|
|
set(_env "")
|
|
foreach(_export ${_arg_ENVIRONMENT_EXPORTS})
|
|
if (NOT DEFINED "${_export}")
|
|
message(FATAL_ERROR "${_export} is not known when trying to export it to qdoc.")
|
|
endif()
|
|
list(APPEND _env "${_export}=${${_export}}")
|
|
endforeach()
|
|
|
|
set(_full_qdoc_command "${_qdoc}")
|
|
if (_env)
|
|
set(_full_qdoc_command "${CMAKE_COMMAND}" "-E" "env" ${_env} "${_qdoc}")
|
|
endif()
|
|
|
|
if (_arg_HTML_DIR STREQUAL "")
|
|
set(_arg_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc")
|
|
endif()
|
|
|
|
get_filename_component(_target "${_qdocconf_file}" NAME_WE)
|
|
|
|
set(_html_outputdir "${_arg_HTML_DIR}/${_target}${_arg_POSTFIX}")
|
|
file(MAKE_DIRECTORY "${_html_outputdir}")
|
|
|
|
set(_qdoc_include_args "")
|
|
if (_arg_INCLUDE_DIRECTORIES OR _arg_FRAMEWORK_PATHS)
|
|
# pass include directories to qdoc via hidden @ option, since we need to generate a file
|
|
# to be able to resolve the generators inside the include paths
|
|
set(_qdoc_includes "${CMAKE_CURRENT_BINARY_DIR}/cmake/qdoc_${_target}.inc")
|
|
set(_qdoc_include_args "@${_qdoc_includes}")
|
|
set(_includes "")
|
|
if (_arg_INCLUDE_DIRECTORIES)
|
|
set(_includes "-I$<JOIN:${_arg_INCLUDE_DIRECTORIES},\n-I>\n")
|
|
endif()
|
|
set(_frameworks "")
|
|
if (_arg_FRAMEWORK_PATHS)
|
|
set(_frameworks "-F$<JOIN:${_arg_FRAMEWORK_PATHS},\n-F>\n")
|
|
endif()
|
|
file(GENERATE
|
|
OUTPUT "${_qdoc_includes}"
|
|
CONTENT "${_includes}${_frameworks}"
|
|
)
|
|
endif()
|
|
|
|
set(_html_target "html_docs_${_target}")
|
|
add_custom_target("${_html_target}"
|
|
${_full_qdoc_command} -outputdir "${_html_outputdir}" "${_qdocconf_file}"
|
|
${_qdoc_index_args} ${_qdoc_include_args}
|
|
COMMENT "Build HTML documentation from ${_qdocconf_file}"
|
|
DEPENDS "${_qdocconf_file}"
|
|
SOURCES "${_qdocconf_file}"
|
|
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
|
|
VERBATIM
|
|
)
|
|
add_dependencies(html_docs "${_html_target}")
|
|
|
|
# Install HTML files as a special component
|
|
install(DIRECTORY "${_html_outputdir}" DESTINATION "${_arg_INSTALL_DIR}"
|
|
COMPONENT ${_html_target} EXCLUDE_FROM_ALL)
|
|
|
|
add_custom_target("install_${_html_target}"
|
|
"${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=${_html_target}
|
|
-P "${CMAKE_BINARY_DIR}/cmake_install.cmake"
|
|
COMMENT "Install HTML documentation from ${_qdocconf_file}"
|
|
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
|
|
VERBATIM
|
|
)
|
|
add_dependencies(install_docs "install_${_html_target}")
|
|
|
|
add_custom_target("clean_${_html_target}"
|
|
"${CMAKE_COMMAND}" -E remove_directory "${_html_outputdir}"
|
|
COMMENT "Clean HTML documentation from ${_qdocconf_file}"
|
|
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
|
|
VERBATIM
|
|
)
|
|
add_dependencies(clean_docs "clean_${_html_target}")
|
|
|
|
set("${_retval}" "${_html_outputdir}" PARENT_SCOPE)
|
|
endfunction()
|
|
|
|
function(_setup_qhelpgenerator_targets _qdocconf_file _html_outputdir)
|
|
cmake_parse_arguments(_arg "" "QCH_DIR;INSTALL_DIR" "" ${ARGN})
|
|
if (_arg_UNPARSED_ARGUMENTS)
|
|
message(FATAL_ERROR "qdoc_build_qdocconf_file has unknown arguments: ${_arg_UNPARSED_ARGUMENTS}.")
|
|
endif()
|
|
|
|
if (NOT _arg_QCH_DIR)
|
|
set(_arg_QCH_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc")
|
|
endif()
|
|
|
|
if (NOT TARGET Qt5::qhelpgenerator)
|
|
message(WARNING "qhelpgenerator missing: No QCH documentation targets were generated")
|
|
return()
|
|
endif()
|
|
|
|
get_filename_component(_target "${_qdocconf_file}" NAME_WE)
|
|
|
|
set(_qch_outputdir "${_arg_QCH_DIR}")
|
|
file(MAKE_DIRECTORY "${_qch_outputdir}")
|
|
|
|
set(_qch_target "qch_docs_${_target}")
|
|
set(_html_target "html_docs_${_target}")
|
|
add_custom_target("${_qch_target}"
|
|
Qt5::qhelpgenerator "${_html_outputdir}/${_target}.qhp" -o "${_qch_outputdir}/${_target}.qch"
|
|
COMMENT "Build QCH documentation from ${_qdocconf_file}"
|
|
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
|
|
VERBATIM
|
|
)
|
|
add_dependencies("${_qch_target}" "${_html_target}")
|
|
add_dependencies(qch_docs "${_qch_target}")
|
|
|
|
install(FILES "${_qch_outputdir}/${_target}.qch" DESTINATION "${_arg_INSTALL_DIR}"
|
|
COMPONENT ${_qch_target} EXCLUDE_FROM_ALL)
|
|
|
|
add_custom_target("install_${_qch_target}"
|
|
"${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=${_qch_target}
|
|
-P "${CMAKE_BINARY_DIR}/cmake_install.cmake"
|
|
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
|
|
VERBATIM
|
|
)
|
|
add_dependencies(install_docs "install_${_qch_target}")
|
|
|
|
add_custom_target("clean_${_qch_target}"
|
|
"${CMAKE_COMMAND}" -E remove -f "${_qch_outputdir}/${_target}.qch"
|
|
COMMENT "Clean QCH documentation generated from ${_qdocconf_file}"
|
|
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
|
|
VERBATIM
|
|
)
|
|
add_dependencies(clean_docs "clean_${_qch_target}")
|
|
endfunction()
|
|
|
|
# Helper functions:
|
|
function(qdoc_build_qdocconf_file _qdocconf_file)
|
|
_setup_doc_targets()
|
|
|
|
_doc_find_program(_qdoc NAMES qdoc qdoc-qt5)
|
|
if (_qdoc STREQUAL "_qdoc-NOTFOUND")
|
|
message(WARNING "No qdoc binary found: No documentation targets were generated")
|
|
return()
|
|
endif()
|
|
|
|
cmake_parse_arguments(_arg "QCH" "HTML_DIR;QCH_DIR;INSTALL_DIR;POSTFIX"
|
|
"INDEXES;INCLUDE_DIRECTORIES;FRAMEWORK_PATHS;ENVIRONMENT_EXPORTS" ${ARGN})
|
|
if (_arg_UNPARSED_ARGUMENTS)
|
|
message(FATAL_ERROR "qdoc_build_qdocconf_file has unknown arguments: ${_arg_UNPARSED_ARGUMENTS}.")
|
|
endif()
|
|
|
|
if (NOT _arg_INSTALL_DIR)
|
|
message(FATAL_ERROR "No INSTALL_DIR set when calling qdoc_build_qdocconf_file")
|
|
endif()
|
|
|
|
_setup_qdoc_targets("${_qdocconf_file}" _html_outputdir
|
|
HTML_DIR "${_arg_HTML_DIR}" INSTALL_DIR "${_arg_INSTALL_DIR}"
|
|
INDEXES ${_arg_INDEXES} ENVIRONMENT_EXPORTS ${_arg_ENVIRONMENT_EXPORTS}
|
|
POSTFIX "${_arg_POSTFIX}"
|
|
INCLUDE_DIRECTORIES ${_arg_INCLUDE_DIRECTORIES}
|
|
FRAMEWORK_PATHS ${_arg_FRAMEWORK_PATHS}
|
|
)
|
|
|
|
if (_arg_QCH)
|
|
_setup_qhelpgenerator_targets("${_qdocconf_file}" "${_html_outputdir}"
|
|
QCH_DIR "${_arg_QCH_DIR}" INSTALL_DIR "${_arg_INSTALL_DIR}")
|
|
endif()
|
|
endfunction()
|
|
|
|
### Skip docs setup if that is not needed!
|
|
if (WITH_ONLINE_DOCS OR WITH_DOCS)
|
|
if (WITH_DOCS)
|
|
set(_qch_params "QCH;QCH_DIR;${PROJECT_BINARY_DIR}/${IDE_DOC_PATH}")
|
|
endif()
|
|
|
|
set(_qdoc_params HTML_DIR "${PROJECT_BINARY_DIR}/doc/html")
|
|
list(APPEND _qdoc_params INDEXES "${QT_INSTALL_DOCS}" "${PROJECT_BINARY_DIR}/doc")
|
|
list(APPEND _qdoc_params INSTALL_DIR "${IDE_DOC_PATH}")
|
|
|
|
# Set up environment for qdoc:
|
|
set(QTC_VERSION "${IDE_VERSION_DISPLAY}")
|
|
set(QTCREATOR_COPYRIGHT_YEAR "${IDE_COPYRIGHT_YEAR}")
|
|
set(IDE_SOURCE_TREE "${PROJECT_SOURCE_DIR}")
|
|
string(REPLACE "." "" QTC_VERSION_TAG "${IDE_VERSION}")
|
|
set(QTC_DOCS_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
|
|
set(QDOC_INDEX_DIR "${QT_INSTALL_DOCS}")
|
|
if (QT_INSTALL_DOCS_src)
|
|
set(QT_INSTALL_DOCS "${QT_INSTALL_DOCS_src}")
|
|
endif()
|
|
|
|
list(APPEND _qdoc_params ENVIRONMENT_EXPORTS
|
|
IDE_ID IDE_CASED_ID IDE_DISPLAY_NAME
|
|
|
|
IDE_SOURCE_TREE
|
|
|
|
QTC_DOCS_DIR QTC_VERSION QTC_VERSION_TAG
|
|
|
|
QTCREATOR_COPYRIGHT_YEAR
|
|
|
|
QT_INSTALL_DOCS QDOC_INDEX_DIR)
|
|
|
|
if (WITH_DOCS)
|
|
qdoc_build_qdocconf_file("qtcreator/qtcreator.qdocconf" ${_qch_params} ${_qdoc_params})
|
|
if (BUILD_DEVELOPER_DOCS)
|
|
_find_all_includes(_all_includes _framework_paths)
|
|
qdoc_build_qdocconf_file("qtcreatordev/qtcreator-dev.qdocconf" ${_qch_params} ${_qdoc_params}
|
|
INCLUDE_DIRECTORIES ${_all_includes}
|
|
FRAMEWORK_PATHS ${_framework_paths}
|
|
)
|
|
endif()
|
|
endif()
|
|
if(WITH_ONLINE_DOCS)
|
|
qdoc_build_qdocconf_file("qtcreator/qtcreator-online.qdocconf" ${_qdoc_params})
|
|
if (BUILD_DEVELOPER_DOCS)
|
|
_find_all_includes(_all_includes _framework_paths)
|
|
qdoc_build_qdocconf_file("qtcreatordev/qtcreator-dev-online.qdocconf" ${_qdoc_params}
|
|
INCLUDE_DIRECTORIES ${_all_includes}
|
|
FRAMEWORK_PATHS ${_framework_paths}
|
|
)
|
|
endif()
|
|
endif()
|
|
endif()
|