Add custom targets for documentation

Adds custom targets which take care of generating and installing
documentation files.

Every module has a global set of targets suffixed with the module
name in order for them to be unique when we implement super builds.
The targets are the same as the list below, but replace ${target}
with the module's name. Eg.: docs_qtbase.

For every target which has an qt_add_docs() call, we now create the
following set of custom targets:

* docs_${target}
* html_docs_${target}
* qch_docs_${target}
* prepare_docs_${target}
* generate_docs_${target}
* install_docs_${target}
* install_html_docs_${target}
* install_qch_docs_${target}

Fixes: QTBUG-75859
Change-Id: Ie84cb9a2dedbe7333d9a84f4d73383442deca477
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
This commit is contained in:
Leander Beernaert 2019-09-19 09:38:09 +02:00
parent 4dfb1eca1e
commit 0095ff4e06
4 changed files with 192 additions and 1 deletions

View File

@ -59,6 +59,9 @@ if(NOT QT_BUILD_STANDALONE_TESTS)
#include CoreMacros() for qt6_generate_meta_types()
include(src/corelib/Qt6CoreMacros.cmake)
## Setup documentation
add_subdirectory(doc)
## Visit all the directories:
add_subdirectory(src)
endif()

View File

@ -3211,7 +3211,160 @@ function(qt_add_docs)
endif()
set(target ${ARGV0})
set(doc_project ${ARGV1})
# TODO
set(qdoc_bin "${CMAKE_INSTALL_PREFIX}/bin/qdoc")
set(qtattributionsscanner_bin "${CMAKE_INSTALL_PREFIX}/bin/qtattributionsscanner")
set(qhelpgenerator_bin "${CMAKE_INSTALL_PREFIX}/bin/qhelpgenerator")
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_ouput_dir "${target_bin_dir}/.doc")
# Generate include dir list
set(target_include_dirs_file "${doc_ouput_dir}/includes.txt")
set(include_paths_property "$<TARGET_PROPERTY:${target},INCLUDE_DIRECTORIES>")
if (NOT target_type STREQUAL "INTERFACE_LIBRARY")
file(GENERATE
OUTPUT ${target_include_dirs_file}
CONTENT "-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}/doc/${doc_target}")
set(index_dir "${CMAKE_BINARY_DIR}/doc")
else()
set(qdoc_output_dir "${CMAKE_INSTALL_PREFIX}/doc/${doc_target}")
set(index_dir "${CMAKE_INSTALL_PREFIX}/doc")
endif()
# qtattributionsscanner
add_custom_target(qattributionsscanner_${target}
COMMAND ${qtattributionsscanner_bin}
${PROJECT_SOURCE_DIR}
--filter "QDocModule=${qdoc_target}"
-o "${target_bin_dir}/codeattributions.qdoc"
)
# prepare docs target
set(prepare_qdoc_args
-outputdir "${qdoc_output_dir}"
-installdir "${QT_INSTALL_DIR}/doc"
"${target_source_dir}/${doc_project}"
-prepare
-indexdir "${index_dir}"
-no-link-errors
"${include_path_args}"
)
set(qdoc_env_args
"QT_INSTALL_DOCS=\"${CMAKE_INSTALL_PREFIX}/doc\""
"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}"
)
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})
# generate docs target
set(generate_qdocs_args
-outputdir "${qdoc_output_dir}"
-installdir "${INSTALL_DOCDIR}"
"${target_source_dir}/${doc_project}"
-generate
-indexdir "${index_dir}"
"${include_path_args}"
)
add_custom_target(generate_docs_${target}
COMMAND ${CMAKE_COMMAND} -E env ${qdoc_env_args}
${qdoc_bin}
${generate_qdocs_args}
)
add_dependencies(generate_docs_${target} prepare_docs_${target})
# generate html
set(html_qdocs_args
-outputdir "${qdoc_output_dir}"
-installdir "${INSTALL_DOCDIR}"
"${target_source_dir}/${doc_project}"
-indexdir "${index_dir}"
"${include_path_args}"
)
add_custom_target(html_docs_${target}
COMMAND ${CMAKE_COMMAND} -E env ${qdoc_env_args}
${qdoc_bin}
${html_qdocs_args}
)
add_dependencies(html_docs_${target} generate_docs_${target})
# generate .qch
set(qch_file_name ${doc_target}.qch)
set(qch_file_path ${qdoc_output_dir}/${qch_file_name})
add_custom_target(qch_docs_${target}
COMMAND ${qhelpgenerator_bin}
"${qdoc_output_dir}/${doc_target}.qhp"
-o "${qch_file_path}"
)
add_dependencies(qch_docs_${target} generate_docs_${target})
if (QT_WILL_INSTALL)
add_custom_target(install_html_docs_${target}
COMMAND ${CMAKE_COMMAND} -E copy_directory
"${qdoc_output_dir}"
"${CMAKE_INSTALL_PREFIX}/${INSTALL_DOCDIR}/${doc_target}"
COMMENT "Installing html docs for target {$target}"
)
add_custom_target(install_qch_docs_${target}
COMMAND ${CMAKE_COMMAND} -E copy_if_different
"${qch_file_path}"
"${CMAKE_INSTALL_PREFIX}/${INSTALL_DOCDIR}/${qch_file_name}"
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_dependencies(install_html_docs_${target} html_docs_${target})
add_dependencies(install_qch_docs_${target} qch_docs_${target})
add_custom_target(install_docs_${target})
add_dependencies(install_docs_${target} install_html_docs_${target} install_qch_docs_${target})
add_dependencies(${qt_docs_prepare_target_name} prepare_docs_${target})
add_dependencies(${qt_docs_generate_target_name} generate_docs_${target})
add_dependencies(${qt_docs_html_target_name} html_docs_${target})
add_dependencies(${qt_docs_qch_target_name} qch_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})
add_dependencies(${qt_docs_install_target_name} install_docs_${target})
endfunction()
macro(qt_find_package)

View File

@ -63,6 +63,34 @@ macro(qt_build_repo_begin)
# Decide whether tools will be built.
qt_check_if_tools_will_be_built()
string(TOLOWER ${PROJECT_NAME} project_name_lower)
set(qt_docs_target_name docs_${project_name_lower})
set(qt_docs_prepare_target_name prepare_docs_${project_name_lower})
set(qt_docs_generate_target_name generate_docs_${project_name_lower})
set(qt_docs_html_target_name html_docs_${project_name_lower})
set(qt_docs_qch_target_name qch_docs_${project_name_lower})
set(qt_docs_install_html_target_name install_html_docs_${project_name_lower})
set(qt_docs_install_qch_target_name install_qch_docs_${project_name_lower})
set(qt_docs_install_target_name install_docs_${project_name_lower})
add_custom_target(${qt_docs_target_name})
add_custom_target(${qt_docs_prepare_target_name})
add_custom_target(${qt_docs_generate_target_name})
add_custom_target(${qt_docs_qch_target_name})
add_custom_target(${qt_docs_html_target_name})
add_custom_target(${qt_docs_install_html_target_name})
add_custom_target(${qt_docs_install_qch_target_name})
add_custom_target(${qt_docs_install_target_name})
add_dependencies(${qt_docs_generate_target_name} ${qt_docs_prepare_target_name})
add_dependencies(${qt_docs_html_target_name} ${qt_docs_generate_target_name})
add_dependencies(${qt_docs_target_name} ${qt_docs_html_target_name} ${qt_docs_qch_target_name})
add_dependencies(${qt_docs_install_html_target_name} ${qt_docs_html_target_name})
add_dependencies(${qt_docs_install_qch_target_name} ${qt_docs_qch_target_name})
add_dependencies(${qt_docs_install_target_name} ${qt_docs_install_html_target_name} ${qt_docs_install_qch_target_name})
endmacro()
macro(qt_build_repo_end)

7
doc/CMakeLists.txt Normal file
View File

@ -0,0 +1,7 @@
#
# Copy/Install doc configuration files to the build/install directory
#
qt_path_join(doc_install_dir ${QT_INSTALL_DIR} ${INSTALL_DOCDIR})
qt_copy_or_install(DIRECTORY global DESTINATION ${doc_install_dir})
qt_copy_or_install(DIRECTORY config DESTINATION ${doc_install_dir})