From 98d5581e1684cfcb499600e81e04a7c6fe6685c8 Mon Sep 17 00:00:00 2001
From: Alexandru Croitor <alexandru.croitor@qt.io>
Date: Wed, 22 Jan 2025 12:06:10 +0100
Subject: [PATCH] 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>
---
 cmake/QtDocsHelpers.cmake | 49 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/cmake/QtDocsHelpers.cmake b/cmake/QtDocsHelpers.cmake
index 184f3b62a5a..68de96f9833 100644
--- a/cmake/QtDocsHelpers.cmake
+++ b/cmake/QtDocsHelpers.cmake
@@ -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)