CMake: Add various option to pass extra args to qdoc execution

Calls to qt_internal_add_docs now accept the following options:
- QDOC_EXTRA_ARGS: Extra arguments to pass to qdoc
- QDOC_PREPARE_EXTRA_ARGS: Extra arguments to pass to qdoc prepare
  phase
- QDOC_GENERATE_EXTRA_ARGS: Extra arguments to pass to qdoc generate
  phase

In addition, the following cmake and environment variables can be set
to pass extra arguments to qdoc for all targets:
- QT_QDOC_EXTRA_ARGS
- QT_QDOC_PREPARE_EXTRA_ARGS
- QT_QDOC_GENERATE_EXTRA_ARGS

The cmake variables can also be set at directory-scope, before the
call to qt_internal_add_docs.

Pick-to: 6.8
Task-number: QTBUG-118176
Change-Id: I0e28f3b863d5ca4efd0256432130af1c9c965f9d
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
(cherry picked from commit 948b2f601dd9c7f526497680c5c4928d2793c238)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
This commit is contained in:
Alexandru Croitor 2025-01-22 12:06:10 +01:00 committed by Qt Cherry-pick Bot
parent a764da6902
commit 98d5581e16

View File

@ -34,10 +34,20 @@ endfunction()
# DEFINES - extra environment variable assignments of the form ENV_VAR=VALUE, which should be set
# during qdoc execution.
#
# QDOC_EXTRA_ARGS - extra command-line arguments to pass to qdoc in both prepare and generate
# phases.
#
# QDOC_PREPARE_EXTRA_ARGS - extra command-line arguments to pass to qdoc in the prepare phase.
#
# QDOC_GENERATE_EXTRA_ARGS - extra command-line arguments to pass to qdoc in the generate phase.
#
# Additional environment variables considered:
# QT_INSTALL_DOCS - directory path where the qt docs were expected to be installed, used for
# linking to other built docs. If not set, defaults to the qtbase or qt5 build directory, or the
# install directory extracted from the BuildInternals package.
#
# QT_QDOC_EXTRA_ARGS, QT_QDOC_PREPARE_EXTRA_ARGS, QT_QDOC_GENERATE_EXTRA_ARGS - same as the options
# but can be set as either environment or cmake variables.
function(qt_internal_add_docs)
if(NOT QT_BUILD_DOCS)
return()
@ -67,6 +77,9 @@ function(qt_internal_add_docs)
set(multi_args
INDEX_DIRECTORIES
DEFINES
QDOC_EXTRA_ARGS
QDOC_PREPARE_EXTRA_ARGS
QDOC_GENERATE_EXTRA_ARGS
)
cmake_parse_arguments(PARSE_ARGV 2 arg "${opt_args}" "${single_args}" "${multi_args}")
_qt_internal_validate_all_args_are_parsed(arg)
@ -82,6 +95,18 @@ function(qt_internal_add_docs)
endforeach()
endif()
if(arg_QDOC_EXTRA_ARGS)
list(APPEND qdoc_extra_args ${arg_QDOC_EXTRA_ARGS})
endif()
if(QT_QDOC_EXTRA_ARGS)
list(APPEND qdoc_extra_args ${QT_QDOC_EXTRA_ARGS})
endif()
if(DEFINED ENV{QT_QDOC_EXTRA_ARGS})
list(APPEND qdoc_extra_args $ENV{QT_QDOC_EXTRA_ARGS})
endif()
# If a target is not built (which can happen for tools when crosscompiling), we shouldn't try
# to generate docs.
if(NOT TARGET "${target}")
@ -186,6 +211,18 @@ function(qt_internal_add_docs)
)
endif()
if(arg_QDOC_PREPARE_EXTRA_ARGS)
list(APPEND prepare_qdoc_args ${arg_QDOC_PREPARE_EXTRA_ARGS})
endif()
if(QT_QDOC_PREPARE_EXTRA_ARGS)
list(APPEND prepare_qdoc_args ${QT_QDOC_PREPARE_EXTRA_ARGS})
endif()
if(DEFINED ENV{QT_QDOC_PREPARE_EXTRA_ARGS})
list(APPEND prepare_qdoc_args $ENV{QT_QDOC_PREPARE_EXTRA_ARGS})
endif()
if(DEFINED ENV{QT_INSTALL_DOCS})
if(NOT EXISTS "$ENV{QT_INSTALL_DOCS}")
message(FATAL_ERROR
@ -240,6 +277,18 @@ function(qt_internal_add_docs)
)
endif()
if(arg_QDOC_GENERATE_EXTRA_ARGS)
list(APPEND generate_qdoc_args ${arg_QDOC_GENERATE_EXTRA_ARGS})
endif()
if(QT_QDOC_GENERATE_EXTRA_ARGS)
list(APPEND generate_qdoc_args ${QT_QDOC_GENERATE_EXTRA_ARGS})
endif()
if(DEFINED ENV{QT_QDOC_GENERATE_EXTRA_ARGS})
list(APPEND generate_qdoc_args $ENV{QT_QDOC_GENERATE_EXTRA_ARGS})
endif()
foreach(target_prefix generate_top_level_docs generate_repo_docs generate_docs)
set(depends_arg "")
if(tool_dependencies_enabled)