doxygen docs and making shared volume and material pointers in gsystem instead of unique

Author: maureeungaro

actions/gactionsDoxy.h

@@ -0,0 +1,10 @@
+/**
+* \mainpage GActions
+ *
+ * @section intro_sec Introduction
+ *
+ * \n\n
+ * \author \n © Maurizio Ungaro
+ * \author e-mail: ungaro@jlab.org
+ * \n\n\n
+ */

ci/generate_html.py

@@ -1,6 +1,17 @@
 #!/usr/bin/env python3
 
 import os
+import html
+
+modules_map = {
+    "base": "guts goptions glogging gbase textProgressBar utilities",
+    "plugins": "gfactory gdynamicDigitization gsd",
+    "hits": "gtouchable ghit",
+    "gui": "gboard gqtbuttonswidget g4display g4dialog gsplash gtree dbselect gui",
+    "detector": "gsystem g4system gdetector gtranslationTable",
+    "i/o": "gdata gstreamer eventDispenser",
+    "geant4": "gparticle gphysics gfields actions",
+}
 
 # Path to the directory containing subdirectories with Doxygen documentation
 pages_directory = "pages"
@@ -16,72 +27,84 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Doxygen Documentation Links</title>
     <style>
+        :root {
+            --fg: #24292f;
+            --muted: #57606a;
+            --border: #d0d7de;
+            --link: #0969da;
+            --bg: #ffffff;
+        }
+
         body {
-            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
             margin: 0;
-            padding: 0;
-            background-color: #f4f4f9;
-            color: #333;
-            display: flex;
-            justify-content: center;
-            align-items: center;
-            min-height: 100vh;
+            background: var(--bg);
+            color: var(--fg);
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
         }
 
+        /* GitHub-ish readable content width */
         .container {
-            text-align: center;
-            padding: 120px;
-            background-color: #ffffff;
-            box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
-            border-radius: 10px;
-            width: 90%;
-            max-width: 600px;
-        }
-
-        h1 {
-            color: #4a90e2;
-            margin-bottom: 10px;
+            max-width: 980px;
+            margin: 0 auto;
+            padding: 32px 24px 24px 24px;
         }
 
+        /* Intro line like a README paragraph */
         p {
-            color: #555;
-            font-size: 1.1em;
-            margin-bottom: 20px;
+            margin: 0 0 16px 0;
+            color: var(--muted);
+            font-size: 16px;
+            line-height: 1.5;
         }
 
+        /* Outer list holds sections (footer expects one outer <ul>) */
         .link-list {
-            display: flex;
-            flex-wrap: wrap;
-            justify-content: center;
+            list-style: none;
             padding: 0;
-            margin: 0;
+            margin: 16px 0 0 0;
+        }
+
+        /* Each section as a list item */
+        .section {
+            margin: 0 0 20px 0;
+        }
+
+        /* “Same font as ## but smaller” */
+        .section-title {
+            font-weight: 600;
+            font-size: 18px;          /* smaller than typical H2 */
+            line-height: 1.25;
+            margin: 24px 0 10px 0;
+            padding-bottom: 6px;
+            border-bottom: 1px solid var(--border);
+        }
+
+        /* Links under each section */
+        .section-links {
             list-style: none;
+            padding: 0;
+            margin: 10px 0 0 0;
+
+            /* compact grid-ish layout without “button” styling */
+            column-count: {{NUM_COLUMNS}};
+            column-gap: 18px;
         }
 
-        .link-list li {
-            margin: 10px;
-            flex: 0 1 calc(100% / {{NUM_COLUMNS}} - 20px);
-            display: flex;
-            justify-content: center;
+        .section-links li {
+            break-inside: avoid;
+            margin: 6px 0;
         }
 
-        .link-list a {
+        a {
+            color: var(--link);
             text-decoration: none;
-            color: #ffffff;
-            background-color: #333392;
-            padding: 10px 20px;
-            border-radius: 5px;
-            transition: background-color 0.1s;
-            display: inline-block;
-            width: 100%;
-            max-width: 300px;
-            text-align: center;
         }
 
-        .link-list a:hover {
-            background-color: #4a70e2;
+        a:hover {
+            text-decoration: underline;
         }
 
+        /* Keep footer styles as originally referenced */
         .footer {
             margin-top: 20px;
             font-size: 0.9em;
@@ -95,7 +118,7 @@
         <ul class="link-list">
 """
 
-# HTML template for the footer
+# HTML template for the footer (KEEP AS IS)
 html_footer = """
         </ul>
         <div class="footer">
@@ -110,31 +133,79 @@
 """
 
 
-def generate_html(directory: str, columns: int) -> str:
-    """Generate the index.html content listing subdirectories alphabetically."""
-    links = ""
+def _existing_doc_dirs(directory: str) -> dict[str, str]:
+    """
+    Return {subdir_name: relative_index_file} for subdirectories that contain index.html.
+    """
+    out: dict[str, str] = {}
+    for name in sorted(os.listdir(directory), key=str.casefold):
+        subdir_path = os.path.join(directory, name)
+        if not os.path.isdir(subdir_path):
+            continue
+        index_file = os.path.join(subdir_path, "index.html")
+        if not os.path.exists(index_file):
+            continue
+        out[name] = os.path.relpath(index_file, directory)
+    return out
 
+
+def generate_html(directory: str, columns: int) -> str:
+    """Generate the index.html content listing subdirectories organized by modules_map."""
     # Clamp columns to at least 1 (avoids division by zero / bad CSS)
     columns = max(1, int(columns))
 
-    # Alphabetical order (case-insensitive)
-    subdirs = sorted(os.listdir(directory), key=str.casefold)
+    existing = _existing_doc_dirs(directory)
+    used: set[str] = set()
 
-    for subdir in subdirs:
-        subdir_path = os.path.join(directory, subdir)
-        if not os.path.isdir(subdir_path):
-            continue
+    sections_html: list[str] = []
 
-        index_file = os.path.join(subdir_path, "index.html")
-        if not os.path.exists(index_file):
+    # Build sections in insertion order of modules_map
+    for section_name, modules_str in modules_map.items():
+        modules = [m for m in modules_str.split() if m.strip()]
+        # Only include modules that actually exist and have index.html
+        present = [m for m in modules if m in existing]
+        if not present:
             continue
 
-        # Link relative to the pages directory
-        relative_index_file = os.path.relpath(index_file, directory)
-        links += f'            <li><a href="{relative_index_file}" target="_blank">{subdir}</a></li>\n'
+        used.update(present)
+
+        section_title = html.escape(section_name)
+        section_block = [
+            '            <li class="section">\n',
+            f'                <div class="section-title">{section_title}</div>\n',
+            '                <ul class="section-links">\n',
+        ]
+
+        for m in present:
+            href = html.escape(existing[m], quote=True)
+            label = html.escape(m)
+            # Text must visibly include square brackets: [ link ]
+            section_block.append(f'                    <li><a href="{href}" target="_blank">[ {label} ]</a></li>\n')
+
+        section_block.append("                </ul>\n")
+        section_block.append("            </li>\n")
+        section_block.append("            <br/>\n")
+        sections_html.append("".join(section_block))
+
+    # Optional: any leftover documented dirs not in modules_map
+    leftovers = sorted([k for k in existing.keys() if k not in used], key=str.casefold)
+    if leftovers:
+        section_block = [
+            '            <li class="section">\n',
+            '                <div class="section-title">other</div>\n',
+            '                <ul class="section-links">\n',
+        ]
+        for m in leftovers:
+            href = html.escape(existing[m], quote=True)
+            label = html.escape(m)
+            section_block.append(f'                    <li><a href="{href}" target="_blank">[ {label} ]</a></li>\n')
+        section_block.append("                </ul>\n")
+        section_block.append("            </li>\n")
+        section_block.append("            <br/>\n")
+        sections_html.append("".join(section_block))
 
     header = html_header.replace("{{NUM_COLUMNS}}", str(columns))
-    return header + links + html_footer
+    return header + "".join(sections_html) + html_footer
 
 
 def write_html_file(directory: str, columns: int) -> None:

dbselect/dbselectDoxy.h

@@ -0,0 +1,10 @@
+/**
+* \mainpage GDetector
+ *
+ * @section intro_sec Introduction
+ *
+ * \n\n
+ * \author \n © Maurizio Ungaro
+ * \author e-mail: ungaro@jlab.org
+ * \n\n\n
+ */

g4dialog/g4dialogDoxy.h

@@ -0,0 +1,10 @@
+/**
+* \mainpage G4Dialog
+ *
+ * @section intro_sec Introduction
+ *
+ * \n\n
+ * \author \n © Maurizio Ungaro
+ * \author e-mail: ungaro@jlab.org
+ * \n\n\n
+ */

gboard/examples/gboard_example.cc

@@ -11,8 +11,42 @@
 #include <QMainWindow>
 #include <QTimer>
 
+/**
+ * @file gboard_example.cc
+ * @brief Example program showing how to route Geant4 output into a GBoard widget.
+ *
+ * This example demonstrates two modes:
+ * - **GUI mode** (enabled with \c --gui): creates a \c QApplication, shows a \c QMainWindow containing GBoard,
+ *   and installs a GUI_Session so Geant4 output is forwarded to the board.
+ * - **CLI mode** (default): runs without creating Qt objects and simply exits after setup messages.
+ *
+ * The example also supports a timeout (scalar option \c tt) that automatically quits the Qt event loop
+ * after the specified duration.
+ *
+ * Key behaviors illustrated:
+ * - Creating module options via \c gboard::defineOptions().
+ * - Constructing a GBoard owned by the Qt parent (the main window).
+ * - Creating a GUI_Session that forwards Geant4 output to the board (session does not own the board).
+ * - Running and terminating a Qt event loop using \c QTimer.
+ */
+
+/**
+ * @brief Entry point for the gboard example application.
+ *
+ * Responsibilities:
+ * - Initializes options and logging.
+ * - Optionally initializes Qt GUI objects and shows a window that embeds GBoard.
+ * - Initializes a Geant4 visualization manager to ensure Geant4 subsystems are active for the demo.
+ * - In GUI mode, installs GUI_Session to route Geant4 UI output to the board.
+ * - Exits either after the Qt event loop ends (GUI) or immediately (CLI).
+ *
+ * @param argc Standard C/C++ argument count.
+ * @param argv Standard C/C++ argument vector.
+ * @return \c EXIT_SUCCESS on normal completion, otherwise a non-zero status.
+ */
 int main(int argc, char* argv[]) {
-	// Initialize options and logging
+	// Initialize options and logging.
+	// The options structure is shared across module components via shared_ptr.
 	auto gopts   = std::make_shared<GOptions>(argc, argv, gboard::defineOptions());
 	auto log     = std::make_shared<GLogger>(gopts, SFUNCTION_NAME, GBOARD_LOGGER);
 	auto gui     = gopts->getSwitch("gui");
@@ -21,7 +55,8 @@ int main(int argc, char* argv[]) {
 
 	log->info(0, "Starting gboard example...");
 
-	// Optional GUI setup (only if --gui is passed)
+	// Optional GUI setup (only if --gui is passed).
+	// Note: We allocate Qt objects dynamically here because the example explicitly deletes them.
 	QApplication* app    = nullptr;
 	QMainWindow*  window = nullptr;
 
@@ -32,17 +67,24 @@ int main(int argc, char* argv[]) {
 		window->setWindowTitle(QString::fromUtf8("displayUI example"));
 	}
 
+	// Initialize Geant4 visualization manager.
+	// This is included to resemble the typical environment where Geant4 produces UI output.
 	auto visManager = new G4VisExecutive;
 	visManager->Initialize();
 
-	// If GUI, show the window and run Qt loop
+	// If GUI, show the window and run Qt loop.
 	if (gui) {
-		auto* gboard      = new GBoard(gopts, window);
-		auto  gui_session = std::make_unique<GUI_Session>(gopts, gboard);
+		// GBoard is parented to the window, but the example explicitly deletes it at the end as well.
+		auto* gboard = new GBoard(gopts, window);
+
+		// GUI_Session installs itself as Geant4 cout destination and forwards to the board.
+		// The session does not own the board.
+		auto gui_session = std::make_unique<GUI_Session>(gopts, gboard);
+
 		window->setCentralWidget(gboard);
 		window->show();
 
-		// quit after timeout
+		// Quit after timeout: this demonstrates deterministic shutdown for automated runs.
 		QTimer::singleShot(timeout, [] {
 			QCoreApplication::quit(); // stop the event loop
 		});
@@ -54,7 +96,7 @@ int main(int argc, char* argv[]) {
 		delete app;
 	}
 	else {
-		// CLI mode
+		// CLI mode: no Qt objects are created.
 		log->info(0, "Running gboard in command line mode...");
 	}