yes, I think it works

Author: SpectraL519

docs/cpp-gl/gl_traits.md

@@ -70,8 +70,14 @@ Requirements for properties that support binary coloring algorithms.
 
 Requires a property type that:
 Satisfies c_properties.
+
+
 Has a nested `color_type`.
+
+
 Has a public `color` member of the `color_type` type.
+
+
 Supports construction and comparison with `[`gl::binary_color`](classgl_1_1binary__color.md)`.
 
 ### Template Parameters
@@ -490,6 +496,25 @@ Validates if a property type contains actual user-defined data.
 
 Requires that the type satisfies [`gl::traits::c_properties`](gl_traits.md#gl-traits-c-properties) and is not the [`gl::empty_properties`](structgl_1_1empty__properties.md) tag.
 
+
+> [!NOTE] Highlights information that users should take into account, even when skimming.
+
+
+
+> [!TIP] Optional information to help a user be more successful.
+
+
+
+> [!IMPORTANT] Crucial information necessary for users to succeed.
+
+
+
+> [!WARNING] Critical content demanding immediate user attention due to potential risks.
+
+
+
+> [!CAUTION] Negative potential consequences of an action.
+
 ### Template Parameters
 
 | Parameter | Description |
@@ -736,7 +761,11 @@ Requirements for properties that support arithmetic weight values.
 
 Requires a property type that:
 Satisfies c_properties.
+
+
 Has a nested `weight_type` that satisfies c_arithmetic.
+
+
 Has a public `weight` member of the `weight_type` type.
 
 ### Template Parameters

include/gl/types/properties.hpp

@@ -260,6 +260,21 @@ concept c_empty_properties = c_properties<T> and std::same_as<T, gl::empty_prope
 /// Requires that the type satisfies @ref gl::traits::c_properties and is not the @ref gl::empty_properties tag.
 ///
 /// @tparam T The type to evaluate against the concept.
+///
+/// > [!NOTE]
+/// > Highlights information that users should take into account, even when skimming.
+///
+/// > [!TIP]
+/// > Optional information to help a user be more successful.
+///
+/// > [!IMPORTANT]
+/// > Crucial information necessary for users to succeed.
+///
+/// > [!WARNING]
+/// > Critical content demanding immediate user attention due to potential risks.
+///
+/// > [!CAUTION]
+/// > Negative potential consequences of an action.
 template <typename T>
 concept c_non_empty_properties = c_properties<T> and not c_empty_properties<T>;
 

scripts/gen_concept_docs.py

@@ -40,6 +40,10 @@ def xml_to_md(elem):
     if elem is None:
         return ""
 
+    # Ignore template parameter lists (they are handled separately for the table)
+    if elem.tag == 'parameterlist':
+        return ""
+
     res = elem.text or ""
     for child in elem:
         if child.tag == 'ref':
@@ -49,17 +53,14 @@ def xml_to_md(elem):
             # 1. Known Concepts: Link exactly to their file and anchor
             if refid in GLOBAL_CONCEPT_LINKS:
                 res += f"[`{ref_text}`]({GLOBAL_CONCEPT_LINKS[refid]})"
-
-            # 2. External/Unknown Concepts (Fallback)
+            # 2. External/Unknown Concepts
             elif refid.startswith('concept'):
                 ref_anchor = ref_text.replace("::", "-").replace("_", "-")
                 res += f"[`{ref_text}`](#{ref_anchor})"
-
-            # 3. Classes, Structs, Namespaces (Fix: MkDoxy generates flat files!)
+            # 3. Classes, Structs, Namespaces (Matches MkDoxy's flat file structure)
             elif refid.startswith('class') or refid.startswith('struct') or refid.startswith('namespace'):
                 res += f"[`{ref_text}`]({refid}.md)"
-
-            # 4. Unknown type (Degrade gracefully to code font)
+            # 4. Unknown
             else:
                 res += f"`{ref_text}`"
 
@@ -70,10 +71,23 @@ def xml_to_md(elem):
         elif child.tag == 'emphasis':
             res += f"*{xml_to_md(child)}*"
         elif child.tag == 'itemizedlist':
-            res += "\n"
+            res += "\n\n"
             for item in child.findall('listitem'):
                 res += f"- {xml_to_md(item).strip()}\n"
-            res += "\n"
+            res += "\n\n"
+        elif child.tag == 'blockquote':
+            # Restores Markdown blockquotes (> [!NOTE]) from Doxygen XML
+            bq_text = xml_to_md(child).strip()
+            res += "\n\n" + "\n".join(f"> {line}" for line in bq_text.splitlines()) + "\n\n"
+        elif child.tag == 'simplesect':
+            # Converts native Doxygen @note, @warning into MkDocs Admonitions
+            kind = child.get('kind', 'note').upper()
+            sect_text = xml_to_md(child).strip()
+            res += f"\n\n> [!{kind}]\n" + "\n".join(f"> {line}" for line in sect_text.splitlines()) + "\n\n"
+        elif child.tag == 'para':
+            res += xml_to_md(child).strip() + "\n\n"
+        elif child.tag == 'title':
+            res += f"### {xml_to_md(child).strip()}\n\n"
         else:
             res += xml_to_md(child)
 
@@ -92,40 +106,32 @@ def parse_concept_xml(xml_path):
     name = root.findtext('compoundname')
     anchor = name.replace("::", "-").replace("_", "-")
 
-    # Extract descriptions using the Markdown-aware parser
     brief = xml_to_md(root.find('briefdescription')).strip()
 
-    details = ""
     params = []
-
     detailed_desc = root.find('detaileddescription')
     if detailed_desc is not None:
-        for para in detailed_desc.findall('para'):
-            param_list = para.find('.//parameterlist[@kind="templateparam"]')
-            if param_list is not None:
-                for item in param_list.findall('parameteritem'):
-                    p_name = xml_to_md(item.find('.//parametername')).strip()
-                    p_desc = xml_to_md(item.find('.//parameterdescription')).strip()
-                    params.append({"name": p_name, "desc": p_desc})
-                para.remove(param_list) # Remove so it isn't rendered twice
-
-            para_text = xml_to_md(para).strip()
-            if para_text:
-                details += para_text + "\n\n"
-
-    # Safely extract definition using strict get_text (NO Markdown allowed)
+        # Extract template parameters safely to build the Markdown Table
+        for param_list in detailed_desc.findall('.//parameterlist[@kind="templateparam"]'):
+            for item in param_list.findall('parameteritem'):
+                p_name = xml_to_md(item.find('.//parametername')).strip()
+                p_desc = xml_to_md(item.find('.//parameterdescription')).strip()
+                params.append({"name": p_name, "desc": p_desc})
+            # Clear the XML node so it isn't rendered twice in the main details block
+            param_list.clear()
+
+    # Process the entire remaining detailed description (including blockquotes)
+    details = xml_to_md(detailed_desc).strip()
+
+    # Extract C++ definition (No Markdown allowed here!)
     constraint = get_text(root.find('initializer')).strip()
+    constraint = re.sub(r'=\s+', '= ', constraint) # Clean Doxygen spacing
 
-    # Fix Doxygen's weird spacing injections (e.g. '=  c_properties')
-    constraint = re.sub(r'=\s+', '= ', constraint)
-
-    # Check if Doxygen already included the 'template <...>' keyword
     if constraint.startswith("template"):
         definition = constraint
         if not definition.endswith(";"):
             definition += ";"
     else:
-        # Fallback for older Doxygen versions
         template_decl = "template <"
         tpl_nodes = root.findall('.//templateparamlist/param')
         tpl_strings = [get_text(p.find('type')).strip() for p in tpl_nodes]
@@ -136,7 +142,7 @@ def parse_concept_xml(xml_path):
         "name": name,
         "anchor": anchor,
         "brief": brief,
-        "details": details.strip(),
+        "details": details,
         "params": params,
         "definition": definition
     }

tests/source/gl/test_alg_coloring.cpp

@@ -82,14 +82,18 @@ TEST_CASE_TEMPLATE_DEFINE("bipartite coloring tests", TraitsType, traits_type_te
 
             fs::path coloring_file_path = data_path / "bicoloring_bipartite_graph_coloring.txt";
 
+            // Using uint8_t results in invalid value interpretation when reading from file
+            // Solution: the data is read as uint16_t and cast to uint8_t
             const auto coloring_values =
                 load_list<std::uint16_t>(sut.n_vertices(), coloring_file_path);
 
             std::transform(
                 coloring_values.begin(),
                 coloring_values.end(),
                 std::back_inserter(expected_coloring),
-                [](const std::uint16_t value) { return gl::bin_color_value{value}; }
+                [](const std::uint16_t value) {
+                    return gl::bin_color_value{static_cast<std::uint8_t>(value)};
+                }
             );
         }