From 1090d31e0360022b4414d0c3cbf27927a7d55901 Mon Sep 17 00:00:00 2001
From: Bradley Lowekamp <blowekamp@mail.nih.gov>
Date: Thu, 23 Jan 2025 14:47:45 -0500
Subject: [PATCH] ENH: Convert to python itkgroup script

---
 Utilities/Doxygen/CMakeLists.txt   |  8 +--
 Utilities/Doxygen/itkdoxygen.pl.in |  9 ---
 Utilities/Doxygen/itkgroup.py      | 89 ++++++++++++++++++++++++++++++
 3 files changed, 91 insertions(+), 15 deletions(-)
 delete mode 100644 Utilities/Doxygen/itkdoxygen.pl.in
 create mode 100755 Utilities/Doxygen/itkgroup.py

diff --git a/Utilities/Doxygen/CMakeLists.txt b/Utilities/Doxygen/CMakeLists.txt
index 05d96781209..b766b9f64cd 100644
--- a/Utilities/Doxygen/CMakeLists.txt
+++ b/Utilities/Doxygen/CMakeLists.txt
@@ -5,7 +5,6 @@ if(ITK_BUILD_DOCUMENTATION)
   find_package(Doxygen)
   find_package(Gnuplot)
   find_package(HTMLHelp)
-  find_package(Perl)
   find_package(Wget)
 endif()
 
@@ -109,12 +108,9 @@ mark_as_advanced(
   ITK_DOXYGEN_XML
   ITK_DOXYGEN_SERVER_BASED_SEARCH)
 
-find_package(Perl)
+if(Python3_EXECUTABLE)
+  set(ITK_DOXYGEN_INPUT_FILTER "${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/itkgroup.py")
 
-if(PERL_FOUND)
-  set(ITK_DOXYGEN_INPUT_FILTER "${PERL_EXECUTABLE} ${ITK_BINARY_DIR}/Utilities/Doxygen/itkdoxygen.pl")
-
-  configure_file(${ITK_SOURCE_DIR}/Utilities/Doxygen/itkdoxygen.pl.in ${ITK_BINARY_DIR}/Utilities/Doxygen/itkdoxygen.pl)
 else()
   set(ITK_DOXYGEN_INPUT_FILTER)
 endif()
diff --git a/Utilities/Doxygen/itkdoxygen.pl.in b/Utilities/Doxygen/itkdoxygen.pl.in
deleted file mode 100644
index f5c6f2a870a..00000000000
--- a/Utilities/Doxygen/itkdoxygen.pl.in
+++ /dev/null
@@ -1,9 +0,0 @@
-# for vxl files run the vxl_doxy.pl script, and use itkgroup.pl for all other files
-if ( $ARGV[0] =~ /(vxl|vcl|vnl)/)
-{
-    system ("perl @ITK_SOURCE_DIR@/Utilities/Doxygen/vxl_doxy.pl $ARGV[0]");
-}
-else
-{
-    system ("perl @ITK_SOURCE_DIR@/Utilities/Doxygen/itkgroup.pl $ARGV[0]");
-}
diff --git a/Utilities/Doxygen/itkgroup.py b/Utilities/Doxygen/itkgroup.py
new file mode 100755
index 00000000000..2ef1cd6aa66
--- /dev/null
+++ b/Utilities/Doxygen/itkgroup.py
@@ -0,0 +1,89 @@
+#!/usr/bin/env python
+#
+#  Copyright NumFOCUS
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#         https://www.apache.org/licenses/LICENSE-2.0.txt
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""
+Usage: itkgroup.py <filename>"
+
+Processes the input filename and prints to stdout.
+
+The file has additional Doxygen grouping markers to doxygen comment blocks, where the block does not contain an empty
+ line. This groups multiple functions or variables not separated by a newline, into a single doxygen group allowing
+ the same doxyen comment to apply to all of them.
+
+"""
+
+
+import re
+import sys
+
+ingroup = False
+semicount = 0
+endbracecount = 0
+endparencount = 0
+leading_space = "  "
+savebuffer = ""
+
+
+def process_line(line: str):
+    global ingroup, semicount, endbracecount, endparencount, leading_space, savebuffer
+
+    line = line.rstrip()
+    if re.search(r"\S+", line):
+        match = re.search(r"/\*\*(.*)", line)
+        if match:
+            if ingroup:
+                print(f"{leading_space}/**{savebuffer}")
+            if re.search(r"(\\class|\\brief)", line):
+                print(line)
+            else:
+                savebuffer = f"{match.group(1)}\n"
+                ingroup = True
+                semicount = 0
+                endbracecount = 0
+                endparencount = 0
+                leading_space = re.match(r"(^\s*)", line).group(1)
+        else:
+            if ingroup:
+                savebuffer += f"{line}\n"
+            else:
+                print(line)
+        if re.search(r";", line):
+            semicount += 1
+        if re.search(r"\}", line):
+            endbracecount += 1
+        if re.search(r"\)", line):
+            endparencount += 1
+    else:
+        if ingroup:
+            if endparencount > 1 and (semicount > 1 or endbracecount > 1):
+                print(f"{leading_space}/**@{{{savebuffer}{leading_space}/**@}}*/\n")
+            else:
+                print(f"{leading_space}/**{savebuffer}")
+            savebuffer = ""
+            ingroup = False
+        else:
+            print(line)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python itkgroup.py <filename>")
+        sys.exit(1)
+
+    filename = sys.argv[1]
+    with open(filename) as file:
+        for line in file:
+            process_line(line)