Centralize and document TRACE tags using X-macros (#7657)

* Introduce X-macro-based trace tag definition
- Created trace_tags.def to centralize TRACE tag definitions
- Each tag includes a symbolic name and description
- Set up enum class TraceTag for type-safe usage in TRACE macros

* Add script to generate Markdown documentation from trace_tags.def
- Python script parses trace_tags.def and outputs trace_tags.md

* Refactor TRACE_NEW to prepend TraceTag and pass enum to is_trace_enabled

* trace: improve trace tag handling system with hierarchical tagging

- Introduce hierarchical tag-class structure: enabling a tag class activates all child tags
- Unify TRACE, STRACE, SCTRACE, and CTRACE under enum TraceTag
- Implement initial version of trace_tag.def using X(tag, tag_class, description)
  (class names and descriptions to be refined in a future update)

* trace: replace all string-based TRACE tags with enum TraceTag
- Migrated all TRACE, STRACE, SCTRACE, and CTRACE macros to use enum TraceTag values instead of raw string literals

* trace : add cstring header

* trace : Add Markdown documentation generation from trace_tags.def via mk_api_doc.py

* trace : rename macro parameter 'class' to 'tag_class' and remove Unicode comment in trace_tags.h.

* trace : Add TODO comment for future implementation of tag_class activation

* trace : Disable code related to tag_class until implementation is ready (#7663).

doc/mk_api_doc.py

@@ -184,11 +184,66 @@ def configure_file(template_file_path, output_file_path, substitutions):
     with open(output_file_path, 'w') as f:
         f.write(template_string)
 
+def generate_trace_tag_docs():
+    """Generate trace tag documentation from trace_tags.def file.
+    
+    This function reads the trace_tags.def file and generates a markdown table with the following format:
+    
+    # Z3 Trace Tags Documentation
+    
+    This document contains the trace tags and their descriptions used in Z3.
+    
+    | Tag | Class | Description |
+    |-----|-------|-------------|
+    | Global | Global | Unknown Class |
+    | add_bounds_tactic | arith_bounds_tactic | add bounds tactic |
+    | parser | parser | parser functionality |
+    
+    The def file format should be:
+    X(class, tag, "description")
+    
+    For example:
+    X(Global, Global, "Unknown Class")
+    X(add_bounds_tactic, arith_bounds_tactic, "add bounds tactic")
+    """
+    print("Generating trace tag documentation...")
+    def_file = os.path.join(SCRIPT_DIR, "../src/util/trace_tags.def")
+    output_md = os.path.join(OUTPUT_DIRECTORY, "trace_tags.md")
+    
+    if not os.path.exists(def_file):
+        print(f"Warning: {def_file} not found. Skipping trace tag documentation generation.")
+        return
+        
+    with open(def_file, "r") as f:
+        lines = f.readlines()
+
+    entries = []
+    for line in lines:
+        match = re.match(r'X\(\s*(\w+)\s*,\s*(\w+)\s*,\s*"([^"]+)"\s*\)', line)
+        if match:
+            tag_class, tag, desc = match.groups()
+            entries.append((tag_class, tag, desc))
+
+    mk_dir(os.path.dirname(output_md))
+    with open(output_md, "w", encoding='utf-8') as f:
+        f.write("# Z3 Trace Tags Documentation\n\n")
+        f.write("This document contains the trace tags and their descriptions used in Z3.\n\n")
+        f.write("| Tag | Class | Description |\n")
+        f.write("|-----|-------|-------------|\n")
+        for tag, class_name, desc in sorted(entries):
+            f.write(f"| {tag} | {class_name} | {desc} |\n")
+    
+    print(f"Trace tag documentation has been generated at {output_md}")
+
 try:
     parse_options()
 
     print("Creating temporary directory \"{}\"".format(TEMP_DIR))
     mk_dir(TEMP_DIR)
+    
+    # Generate trace tag documentation
+    generate_trace_tag_docs()
+    
     # Short-hand for path to temporary file
     def temp_path(path):
         return os.path.join(TEMP_DIR, path)