detect SIP version to add DefaultDocstringSignature directive (#6030)

* detect SIP version to add DefaultDocstringSignature directive

SIP doesn't handle any kind of preprocessing, so there's no better solution than configuring the SIP files from CMake.
SIP 4.19.7+ supports %DefaultDocstringSignature to prepend auto-generated Python signature to existing Docstrings

CMakeLists.txt

@@ -704,7 +704,7 @@ IF (WITH_CORE AND WITH_BINDINGS)
   INCLUDE(PyQtMacros)
   INCLUDE(SIPMacros)
 
-  SET(SIP_INCLUDES ${PYQT_SIP_DIR} ${CMAKE_SOURCE_DIR}/python)
+  SET(SIP_INCLUDES ${PYQT_SIP_DIR} ${CMAKE_SOURCE_DIR}/python ${CMAKE_SOURCE_DIR}/python/core)
   SET(SIP_CONCAT_PARTS 4)
 
   IF (NOT BINDINGS_GLOBAL_INSTALL)

cmake/SIPMacros.cmake

@@ -52,6 +52,14 @@ MACRO(GENERATE_SIP_PYTHON_MODULE_CODE MODULE_NAME MODULE_SIP CPP_FILES)
 
   FILE(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${_module_path})    # Output goes in this dir.
 
+  # If this is not need anymore (using input configuration file for SIP modules)
+  # Then SIP could build against the file in the source rather than in CMake current directory
+  # and thus remove the 2 extras includes:
+  # - hereafter in the custom command: -I ${CMAKE_CURRENT_SOURCE_DIR}/${_module_path}
+  # - in top CMakeLists.txt in SIP_INCLUDES declaraiton the core part
+  SET(_configured_module_sip ${CMAKE_CURRENT_BINARY_DIR}/${_module_path}/${_module_path}.sip)
+  CONFIGURE_FILE(${_abs_module_sip}.in ${_configured_module_sip})
+
   SET(_sip_includes)
   FOREACH (_inc ${SIP_INCLUDES})
     GET_FILENAME_COMPONENT(_abs_inc ${_inc} ABSOLUTE)
@@ -99,13 +107,14 @@ MACRO(GENERATE_SIP_PYTHON_MODULE_CODE MODULE_NAME MODULE_SIP CPP_FILES)
     ADD_DEFINITIONS( /bigobj )
   ENDIF(MSVC)
 
-  SET(SIPCMD ${SIP_BINARY_PATH} ${_sip_tags} -w -e ${_sip_x} ${SIP_EXTRA_OPTIONS} -j ${SIP_CONCAT_PARTS} -c ${CMAKE_CURRENT_BINARY_DIR}/${_module_path} ${_sip_includes} ${_abs_module_sip})
+  SET(SIPCMD ${SIP_BINARY_PATH} ${_sip_tags} -w -e ${_sip_x} ${SIP_EXTRA_OPTIONS} -j ${SIP_CONCAT_PARTS} -c ${CMAKE_CURRENT_BINARY_DIR}/${_module_path} -I ${CMAKE_CURRENT_SOURCE_DIR}/${_module_path} ${_sip_includes} ${_configured_module_sip})
   ADD_CUSTOM_COMMAND(
     OUTPUT ${_sip_output_files}
     COMMAND ${CMAKE_COMMAND} -E echo ${message}
     COMMAND ${CMAKE_COMMAND} -E touch ${_sip_output_files}
     COMMAND ${SIPCMD}
-    DEPENDS ${_abs_module_sip} ${SIP_EXTRA_FILES_DEPEND}
+    MAIN_DEPENDENCY ${_configured_module_sip}
+    DEPENDS ${SIP_EXTRA_FILES_DEPEND}
     VERBATIM
   )
 

python/CMakeLists.txt

@@ -171,6 +171,11 @@ IF(NOT QT_MOBILITY_LOCATION_FOUND)
   SET(SIP_DISABLE_FEATURES ${SIP_DISABLE_FEATURES} MOBILITY_LOCATION)
 ENDIF(NOT QT_MOBILITY_LOCATION_FOUND)
 
+# SIP 4.19.7+ can prepend auto-generated Python signature to existing Docstrings
+IF(${SIP_VERSION_STR} VERSION_GREATER 4.19.6)
+  SET(DEFAULTDOCSTRINGSIGNATURE "%DefaultDocstringSignature \"prepended\"")
+ENDIF(${SIP_VERSION_STR} VERSION_GREATER 4.19.6)
+
 # core module
 FILE(GLOB_RECURSE sip_files_core core/*.sip)
 SET(SIP_EXTRA_FILES_DEPEND ${sip_files_core})

python/analysis/analysis.sip.in

@@ -1,6 +1,8 @@
 %Module(name=qgis._analysis,
         keyword_arguments="All")
 
+${DEFAULTDOCSTRINGSIGNATURE}
+
 %Import QtCore/QtCoremod.sip
 %Import QtGui/QtGuimod.sip
 %Import QtXml/QtXmlmod.sip

python/core/core.sip.in

@@ -1,6 +1,8 @@
 %Module(name=qgis._core,
         keyword_arguments="All")
 
+${DEFAULTDOCSTRINGSIGNATURE}
+
 %ModuleCode
 
 #include "qgsexception.h"

python/gui/gui.sip.in

@@ -1,6 +1,8 @@
 %Module(name=qgis._gui,
         keyword_arguments="All")
 
+${DEFAULTDOCSTRINGSIGNATURE}
+
 %Feature HAVE_QSCI_SIP
 
 %Import core/core.sip

python/server/server.sip.in

@@ -1,6 +1,7 @@
 %Module(name=qgis._server,
         keyword_arguments="All")
 
+${DEFAULTDOCSTRINGSIGNATURE}
 
 %Import QtCore/QtCoremod.sip
 %Import QtGui/QtGuimod.sip