1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

CMake: Accept additional arguments for qt_internal_add_docs

Browse Source 
The current implementation of the API accepts only two
arguments, {target} and {qdocconf}. It passes a few
environment variables to build targets, providing info.
about the Qt version being used. QT_INSTALL_DOCS is one
of these environment variables, and it is the install
path for all the Qt module/addon documentation sets.
QT_INSTALL_DOCS is also the path where the global QDoc
configuration files are available.

If a project uses the qt_internal_add_docs to create
the build targets for the documentation, and the Qt
version used to configure the project is a pkg installed
using the qt-online-installer, the QT_INSTALL_DOCS path
is always wrong. Such projects should either maintain a
CMake setup for documentation or configure and
build Qt from source with the correct QT_INSTALL_DOCS
path, which is then passed to qdoc.

This change enables passing additional indexdir
and other arguments to QDoc, which is useful. For example,
if QDoc cannot find all the cross-module link targets,
you could either pass extra indexdir argument to resolve
the links or turn off the link errors.

For example, if your qdocconf has the following depends
entry to enble linking to other modules:

    depends += qtcore qtmultimedia

And the documentation for these modules are not part
of the Qt installation used to build the projects, you
could pass additional index dirs to enable cross-module
linking.

    qt_internal_add_docs{target_name qdocconf
                         INDEX_DIRECTORIES /absolute/path/Qt6/Docs /one/more/Qt6/Docs /another/Qt6/Docs)

Change-Id: Ieac271ddf92990d722602487c41af7f18546d096
Done-with: Topi Reinio <topi.reinio@qt.io>
Task-number: QTBUG-121457
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
(cherry picked from commit c024af0d12e35891e19752c1f7cd6fb3371d09b0)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
This commit is contained in:
Venugopal Shivashankar 2024-01-12 11:48:29 +01:00 committed by Qt Cherry-pick Bot
parent b1138180cc
commit a375e52aa3
1 changed files with 29 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
cmake/QtDocsHelpers.cmake
View File

@ -21,12 +21,37 @@ function(qt_internal_add_docs)
# Function called from old generated CMakeLists.txt that was missing the target parameter
return()
endif()
if(NOT ${ARGC} EQUAL 2)
message(FATAL_ERROR "qt_add_docs called with the wrong number of arguments. Should be qt_add_docs(target path_to_project.qdocconf).")
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)
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.
@ -114,6 +139,7 @@ function(qt_internal_add_docs)
if(NOT QT_BUILD_ONLINE_DOCS)
list(PREPEND prepare_qdoc_args
-installdir "${QT_INSTALL_DIR}/${INSTALL_DOCDIR}"
${qdoc_extra_args}
)
endif()
@ -156,6 +182,7 @@ function(qt_internal_add_docs)
if(NOT QT_BUILD_ONLINE_DOCS)
list(PREPEND generate_qdoc_args
-installdir "${QT_INSTALL_DIR}/${INSTALL_DOCDIR}"
${qdoc_extra_args}
)
endif()