203 lines
7.0 KiB
CMake
203 lines
7.0 KiB
CMake
# SPDX-FileCopyrightText: 2025 Nicolas Fella <nicolas.fella@gmx.de>
|
|
#
|
|
# SPDX-License-Identifier: BSD-3-Clause
|
|
|
|
#[=======================================================================[.rst:
|
|
ECMGenerateQDoc
|
|
------------------
|
|
|
|
This module provides the ``ecm_generate_qdoc`` function for generating API
|
|
documentation files for projects based on qdoc.
|
|
|
|
It allows to generate both online HTML documentation as well as
|
|
(installed) QCH files.
|
|
|
|
::
|
|
|
|
ecm_generate_qdoc(<target_name> <qdocconf_file>)
|
|
|
|
``target_name`` is the library target for which the documentation is generated.
|
|
|
|
``qdocconf_file`` is the .qdocconf file that controls the documentation generation.
|
|
|
|
If the project contains multiple libraries with documented APIs ``ecm_generate_qdoc``
|
|
should be called for each one.
|
|
|
|
Example usage:
|
|
|
|
.. code-block:: cmake
|
|
|
|
ecm_add_qch(KF6::CoreAddons kcoreaddons.qdocconf)
|
|
|
|
Documentation is not built as part of the normal build, it needs to be explicity
|
|
invoked using the following build targets:
|
|
|
|
* ``prepare_docs`` runs the prepare step from qdoc, which processes sources and creates index files
|
|
* ``generate_docs`` runs the generate step from qdoc, generating the final documentation from the index files
|
|
* ``install_html_docs`` installs the generated HTML documentation into ``KDE_INSTALL_QTQCHDIR`` from :kde-module:`KDEInstallDirs`
|
|
* ``generate_qch`` creates QCH files out of the HTML documentation
|
|
* ``install_qch_docs`` installs the QCH files into ``KDE_INSTALL_QTQCHDIR`` from :kde-module:`KDEInstallDirs`
|
|
|
|
The following global parameters are understood:
|
|
|
|
* ``QDOC_BIN``: This can be used to select another qdoc executable than the one found by find_package. This is useful to test with different versions of the qdoc tool.
|
|
* ``DOC_DESTDIR``: This is where the HTML and index files will be generated. This is useful to aggregate results from multiple projects into a single directory.
|
|
|
|
When combining documentation from multiple projects the recommended procedure is to use a common ``DOC_DESTDIR`` and run the prepare stage for all before running the generate stage for all. This ensures that the index files are all available during the generate phase and cross-linking works as expected.
|
|
|
|
Since 6.11.0.
|
|
#]=======================================================================]
|
|
|
|
add_custom_target(prepare_docs)
|
|
add_custom_target(generate_docs)
|
|
add_custom_target(install_html_docs)
|
|
add_custom_target(generate_qch)
|
|
add_custom_target(install_qch_docs)
|
|
|
|
function(ecm_generate_qdoc target qdocconf_file)
|
|
find_package(Qt6Tools CONFIG REQUIRED)
|
|
find_package(Qt6 COMPONENTS ToolsTools CONFIG REQUIRED)
|
|
|
|
if (NOT TARGET ${target})
|
|
message(FATAL_ERROR "${target} is not a target")
|
|
endif()
|
|
|
|
file(REAL_PATH ${qdocconf_file} full_qdocconf_path)
|
|
|
|
if (NOT EXISTS ${full_qdocconf_path})
|
|
message(FATAL_ERROR "Cannot find qdocconf file: ${qdocconf_file}")
|
|
endif()
|
|
|
|
set(qdoc_extra_args "")
|
|
|
|
if (NOT QDOC_BIN)
|
|
get_target_property(QDOC_BIN Qt6::qdoc LOCATION)
|
|
endif()
|
|
|
|
get_target_property(target_type ${target} TYPE)
|
|
get_target_property(target_bin_dir ${target} BINARY_DIR)
|
|
get_target_property(target_source_dir ${target} SOURCE_DIR)
|
|
set(doc_output_dir "${target_bin_dir}/.doc")
|
|
|
|
# Generate include dir list
|
|
set(target_include_dirs_file "${doc_output_dir}/$<CONFIG>/includes.txt")
|
|
|
|
set(include_paths_property "$<TARGET_PROPERTY:${target},INCLUDE_DIRECTORIES>")
|
|
|
|
file(GENERATE
|
|
OUTPUT ${target_include_dirs_file}
|
|
CONTENT "$<$<BOOL:${include_paths_property}>:-I$<JOIN:${include_paths_property},\n-I>>\n-I$<TARGET_PROPERTY:${target},BINARY_DIR>"
|
|
)
|
|
set(include_path_args "@${target_include_dirs_file}")
|
|
|
|
set(dest_dir ${doc_output_dir})
|
|
|
|
if (DOC_DESTDIR)
|
|
set(dest_dir ${DOC_DESTDIR})
|
|
endif()
|
|
|
|
ecm_query_qt(docs_dir QT_INSTALL_DOCS)
|
|
|
|
set(index_dirs ${dest_dir};${docs_dir})
|
|
|
|
foreach(path ${CMAKE_PREFIX_PATH} ${CMAKE_INSTALL_PREFIX})
|
|
if (EXISTS ${path}/${KDE_INSTALL_DATAROOTDIR}/doc)
|
|
list(APPEND ${index_dirs} "${path}/${KDE_INSTALL_DATAROOTDIR}/doc")
|
|
endif()
|
|
endforeach()
|
|
|
|
set(index_dir_arg)
|
|
foreach(index_directory ${index_dirs})
|
|
list(APPEND index_dir_arg "--indexdir" ${index_directory})
|
|
endforeach()
|
|
|
|
|
|
get_filename_component(doc_target "${qdocconf_file}" NAME_WLE)
|
|
set(qdoc_qch_output_dir "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}")
|
|
set(index_dir "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}")
|
|
|
|
# prepare docs target
|
|
set(prepare_qdoc_args
|
|
-outputdir ${dest_dir}/${doc_target}
|
|
"${target_source_dir}/${qdocconf_file}"
|
|
-prepare
|
|
${index_dir_arg}
|
|
-no-link-errors
|
|
-installdir ${dest_dir}
|
|
"${include_path_args}"
|
|
)
|
|
|
|
set(qdoc_env_args
|
|
"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}
|
|
)
|
|
|
|
# generate docs target
|
|
set(generate_qdoc_args
|
|
-outputdir ${dest_dir}/${doc_target}
|
|
"${target_source_dir}/${qdocconf_file}"
|
|
-generate
|
|
${index_dir_arg}
|
|
-installdir ${dest_dir}
|
|
"${include_path_args}"
|
|
)
|
|
|
|
add_custom_target(generate_docs_${target}
|
|
COMMAND ${CMAKE_COMMAND} -E env ${qdoc_env_args}
|
|
${QDOC_BIN}
|
|
${generate_qdoc_args}
|
|
)
|
|
|
|
# generate .qch
|
|
set(qch_file_name ${doc_target}.qch)
|
|
set(qch_file_path ${dest_dir}/${doc_target}/${qch_file_name})
|
|
|
|
get_target_property(QHelpGenerator_EXECUTABLE Qt6::qhelpgenerator LOCATION)
|
|
|
|
add_custom_target(generate_qch_${target}
|
|
COMMAND ${QHelpGenerator_EXECUTABLE}
|
|
"${dest_dir}/html/${doc_target}.qhp"
|
|
-o "${qch_file_path}"
|
|
)
|
|
|
|
add_dependencies(prepare_docs prepare_docs_${target})
|
|
add_dependencies(generate_docs generate_docs_${target})
|
|
add_dependencies(generate_qch generate_qch_${target})
|
|
add_dependencies(install_html_docs install_html_docs_${target})
|
|
add_dependencies(install_qch_docs install_qch_docs_${target})
|
|
|
|
install(DIRECTORY "${dest_dir}/html/"
|
|
DESTINATION "${KDE_INSTALL_QTQCHDIR}/${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 "${KDE_INSTALL_QTQCHDIR}"
|
|
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}"
|
|
)
|
|
endfunction()
|