1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
# 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.
#]=======================================================================]
cmake_policy(VERSION 3.16)
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 QUIET)
find_package(Qt6 OPTIONAL_COMPONENTS ToolsTools CONFIG QUIET)
if (NOT Qt6Tools_FOUND OR NOT Qt6ToolsTools_FOUND)
message(STATUS "Qt6Tools or Qt6ToolsTools not found, not generating API documentation")
return()
endif()
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)
if (NOT TARGET Qt6::qdoc)
message("qdoc executable not found, not generating API documentation")
return()
endif()
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 "${CMAKE_BINARY_DIR}/.doc")
# Generate include dir list
set(target_include_dirs_file "${doc_output_dir}/${target}_$<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}
)
add_dependencies(prepare_docs prepare_docs_${target})
add_dependencies(generate_docs generate_docs_${target})
# generate .qch
if (TARGET Qt6::qhelpgenerator)
set(qch_file_name ${doc_target}.qch)
set(qch_file_path ${dest_dir}/${qch_file_name})
get_target_property(QHelpGenerator_EXECUTABLE Qt6::qhelpgenerator LOCATION)
add_custom_target(generate_qch_${target}
COMMAND ${QHelpGenerator_EXECUTABLE}
"${dest_dir}/${doc_target}/${doc_target}.qhp"
-o "${qch_file_path}"
)
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}/${doc_target}/"
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}"
)
else()
message("qhelpgenerator executable not found, not generating API documentation in QCH format")
endif()
endfunction()
|
