further refinement

Author: SpectraL519

pyproject.toml

@@ -11,4 +11,5 @@ dependencies = [
     "mkdocs-include-markdown-plugin>=7.2.2",
     "mkdocs-material>=9.7.6",
     "mkdoxy>=1.2.8",
+    "ruff>=0.15.11",
 ]

scripts/gen_concept_docs.py

@@ -2,34 +2,48 @@
 import argparse
 import re
 from pathlib import Path
+from dataclasses import dataclass
+
+GROUPS = {
+    "GL": {
+        "prefix": "gl::",
+        "filename": "gl_traits.md",
+        "anchor": "gl-traits-concepts-documentation",
+        "title": "GL Traits & Concepts",
+        "description": "This page documents the C++20 concepts and type traits used to constrain templates across the GL library.",
+    },
+    "HGL": {
+        "prefix": "hgl::",
+        "filename": "hgl_traits.md",
+        "anchor": "hgl-traits-concepts-documentation",
+        "title": "HGL Traits & Concepts",
+        "description": "This page documents the C++20 concepts and type traits used to constrain templates across the HGL library.",
+    },
+}
+
+
+@dataclass
+class TParamDescriptor:
+    name: str
+    desc: str
+
+@dataclass
+class ConceptDescriptor:
+    name: str
+    anchor: str
+    brief: str
+    details: str
+    params: list[TParamDescriptor]
+    definition: str
+
 
 class ConceptParser:
-    # Configuration for module groups
-    GROUPS = {
-        "GL": {
-            "prefix": "gl::",
-            "filename": "gl_traits.md",
-            "anchor": "gl-traits-concepts-documentation",
-            "title": "GL Traits & Concepts",
-            "description": "This page documents the C++20 concepts and type traits used to constrain templates across the GL library."
-        },
-        "HGL": {
-            "prefix": "hgl::",
-            "filename": "hgl_traits.md",
-            "anchor": "hgl-traits-concepts-documentation",
-            "title": "HGL Traits & Concepts",
-            "description": "This page documents the C++20 concepts and type traits used to constrain templates across the HGL library."
-        }
-    }
-
-    # Hidden from the rendered website, but visible to developers opening the raw .md file
-    DEV_WARNING = "\n"
-
-    def __init__(self, xml_dir: Path, out_dir: Path):
+    def __init__(self, xml_dir: Path, out_dir: Path, groups: dict = GROUPS):
         self.xml_dir = xml_dir
         self.out_dir = out_dir
-        self.concept_links = {}         # Registry mapping refid -> file#anchor
-        self.categorized_concepts = {key: [] for key in self.GROUPS.keys()}
+        self.groups = groups
+        self.concept_links = {}  # Registry mapping refid -> file#anchor
+        self.categorized_concepts = {key: [] for key in self.groups.keys()}
 
     @staticmethod
     def _get_text(element: ET.Element) -> str:
@@ -44,49 +58,61 @@ def _xml_to_md(self, elem: ET.Element) -> str:
             return ""
 
         # Ignore template parameter lists (they are handled separately for the table)
-        if elem.tag == 'parameterlist':
+        if elem.tag == "parameterlist":
             return ""
 
         res = elem.text or ""
         for child in elem:
-            if child.tag == 'ref':
+            if child.tag == "ref":
                 ref_text = "".join(child.itertext())
-                refid = child.get('refid', '')
+                refid = child.get("refid", "")
 
-                # 1. Known Concepts: Link using the class registry
+                # Known concept with a registered link
                 if refid in self.concept_links:
                     res += f"[`{ref_text}`]({self.concept_links[refid]})"
-                # 2. External/Unknown Concepts
-                elif refid.startswith('concept'):
+                # External/Unknown Concepts
+                elif refid.startswith("concept"):
                     ref_anchor = ref_text.replace("::", "-").replace("_", "-")
                     res += f"[`{ref_text}`](#{ref_anchor})"
-                # 3. Classes, Structs, Namespaces
-                elif refid.startswith('class') or refid.startswith('struct') or refid.startswith('namespace'):
+                # Classes, Structs, Namespaces
+                elif (
+                    refid.startswith("class")
+                    or refid.startswith("struct")
+                    or refid.startswith("namespace")
+                ):
                     res += f"[`{ref_text}`]({refid}.md)"
                 else:
                     res += f"`{ref_text}`"
 
-            elif child.tag in ['computeroutput', 'preformatted']:
+            elif child.tag in ["computeroutput", "preformatted"]:
                 res += f"`{self._xml_to_md(child)}`"
-            elif child.tag == 'bold':
+            elif child.tag == "bold":
                 res += f"**{self._xml_to_md(child)}**"
-            elif child.tag == 'emphasis':
+            elif child.tag == "emphasis":
                 res += f"*{self._xml_to_md(child)}*"
-            elif child.tag == 'itemizedlist':
+            elif child.tag == "itemizedlist":
                 res += "\n\n"
-                for item in child.findall('listitem'):
+                for item in child.findall("listitem"):
                     res += f"- {self._xml_to_md(item).strip()}\n"
                 res += "\n\n"
-            elif child.tag == 'blockquote':
+            elif child.tag == "blockquote":
                 bq_text = self._xml_to_md(child).strip()
-                res += "\n\n" + "\n".join(f"> {line}" for line in bq_text.splitlines()) + "\n\n"
-            elif child.tag == 'simplesect':
-                kind = child.get('kind', 'note').upper()
+                res += (
+                    "\n\n"
+                    + "\n".join(f"> {line}" for line in bq_text.splitlines())
+                    + "\n\n"
+                )
+            elif child.tag == "simplesect":
+                kind = child.get("kind", "note").upper()
                 sect_text = self._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 += (
+                    f"\n\n> [!{kind}]\n"
+                    + "\n".join(f"> {line}" for line in sect_text.splitlines())
+                    + "\n\n"
+                )
+            elif child.tag == "para":
                 res += self._xml_to_md(child).strip() + "\n\n"
-            elif child.tag == 'title':
+            elif child.tag == "title":
                 res += f"### {self._xml_to_md(child).strip()}\n\n"
             else:
                 res += self._xml_to_md(child)
@@ -95,72 +121,80 @@ def _xml_to_md(self, elem: ET.Element) -> str:
 
         return res
 
-    def _parse_concept_xml(self, xml_path: Path) -> dict | None:
+    def _parse_concept_xml(self, xml_path: Path) -> ConceptDescriptor | None:
         """Parses a single Doxygen concept XML file."""
         tree = ET.parse(xml_path)
-        root = tree.find('compounddef')
+        root = tree.find("compounddef")
 
-        if root is None or root.get('kind') != 'concept':
+        if root is None or root.get("kind") != "concept":
             return None
 
-        name = root.findtext('compoundname')
+        name = root.findtext("compoundname")
         anchor = name.replace("::", "-").replace("_", "-")
-        brief = self._xml_to_md(root.find('briefdescription')).strip()
+        brief = self._xml_to_md(root.find("briefdescription")).strip()
         params = []
 
-        detailed_desc = root.find('detaileddescription')
+        detailed_desc = root.find("detaileddescription")
         if detailed_desc is not None:
-            for param_list in detailed_desc.findall('.//parameterlist[@kind="templateparam"]'):
-                for item in param_list.findall('parameteritem'):
-                    p_name = self._xml_to_md(item.find('.//parametername')).strip()
-                    p_desc = self._xml_to_md(item.find('.//parameterdescription')).strip()
-                    params.append({"name": p_name, "desc": p_desc})
+            for param_list in detailed_desc.findall(
+                './/parameterlist[@kind="templateparam"]'
+            ):
+                for item in param_list.findall("parameteritem"):
+                    p_name = self._xml_to_md(item.find(".//parametername")).strip()
+                    p_desc = self._xml_to_md(
+                        item.find(".//parameterdescription")
+                    ).strip()
+                    params.append(TParamDescriptor(name=p_name, desc=p_desc))
                 param_list.clear()
 
         details = self._xml_to_md(detailed_desc).strip()
 
-        constraint = self._get_text(root.find('initializer')).strip()
-        constraint = re.sub(r'=\s+', '= ', constraint)
+        constraint = self._get_text(root.find("initializer")).strip()
+        constraint = re.sub(r"=\s+", "= ", constraint)
 
         if constraint.startswith("template"):
             definition = constraint
             if not definition.endswith(";"):
                 definition += ";"
         else:
             template_decl = "template <"
-            tpl_nodes = root.findall('.//templateparamlist/param')
+            tpl_nodes = root.findall(".//templateparamlist/param")
             tpl_strings = [self._get_text(p).strip() for p in tpl_nodes]
             template_decl += ", ".join(tpl_strings) + ">\n"
-            definition = f"{template_decl}concept {name.split('::')[-1]} = {constraint};"
-
-        return {
-            "name": name,
-            "anchor": anchor,
-            "brief": brief,
-            "details": details,
-            "params": params,
-            "definition": definition
-        }
+            definition = (
+                f"{template_decl}concept {name.split('::')[-1]} = {constraint};"
+            )
+
+        return ConceptDescriptor(
+            name=name,
+            anchor=anchor,
+            brief=brief,
+            details=details,
+            params=params,
+            definition=definition,
+        )
 
     def process(self):
         """Main execution flow: builds registry, parses data, and generates markdown."""
         index_xml = self.xml_dir / "index.xml"
         if not index_xml.exists():
-            print(f"Error: Could not find Doxygen index at {index_xml}. Run Doxygen first.")
+            print(
+                f"Error: Could not find Doxygen index at {index_xml}. Run Doxygen first."
+            )
             return
 
         tree = ET.parse(index_xml)
 
-        # PASS 1: Build the global concept dictionary for cross-linking
+        # PASS 1: Build the concept registry for cross-linking
         for compound in tree.findall("compound[@kind='concept']"):
-            name = compound.findtext('name')
+            name = compound.findtext("name")
             if not name:
                 continue
 
             refid = compound.get("refid")
             anchor = name.replace("::", "-").replace("_", "-")
 
-            for group_key, group_info in self.GROUPS.items():
+            for group_key, group_info in self.groups.items():
                 if name.startswith(group_info["prefix"]):
                     self.concept_links[refid] = f"{group_info['filename']}#{anchor}"
                     break
@@ -171,8 +205,8 @@ def process(self):
             if xml_path.exists():
                 data = self._parse_concept_xml(xml_path)
                 if data:
-                    for group_key, group_info in self.GROUPS.items():
-                        if data["name"].startswith(group_info["prefix"]):
+                    for group_key, group_info in self.groups.items():
+                        if data.name.startswith(group_info["prefix"]):
                             self.categorized_concepts[group_key].append(data)
                             break
 
@@ -183,41 +217,39 @@ def process(self):
 
     def _generate_group_files(self):
         """Generates the specific group documentation files (e.g., gl_traits.md)."""
-        for group_key, group_info in self.GROUPS.items():
-            self.categorized_concepts[group_key].sort(key=lambda x: x['name'])
+        for group_key, group_info in self.groups.items():
+            self.categorized_concepts[group_key].sort(key=lambda x: x.name)
             concepts = self.categorized_concepts[group_key]
 
-            md = f"{self.DEV_WARNING}\n"
-            md += f"# {group_info['title']} {{: #{group_info['anchor']} }}\n\n"
+            md = f"# {group_info['title']} {{: #{group_info['anchor']} }}\n\n"
             md += f"{group_info['description']}\n\n---\n\n"
 
             if not concepts:
                 md += "*No concepts are currently documented for this module.*\n"
             else:
                 for c in concepts:
-                    md += f"## `{c['name']}` {{: #{c['anchor']} }}\n\n"
-                    if c['brief']:
-                        md += f"{c['brief']}\n\n"
-                    if c['details']:
-                        md += f"### Detailed Description\n\n{c['details']}\n\n"
-                    if c['params']:
+                    md += f"## `{c.name}` {{: #{c.anchor} }}\n\n"
+                    if c.brief:
+                        md += f"{c.brief}\n\n"
+                    if c.details:
+                        md += f"### Detailed Description\n\n{c.details}\n\n"
+                    if c.params:
                         md += "### Template Parameters\n\n| Parameter | Description |\n| :--- | :--- |\n"
-                        for p in c['params']:
-                            md += f"| `{p['name']}` | {p['desc']} |\n"
+                        for p in c.params:
+                            md += f"| `{p.name}` | {p.desc} |\n"
                         md += "\n"
-                    md += f"### Definition\n\n```cpp\n{c['definition']}\n```\n\n---\n\n"
+                    md += f"### Definition\n\n```cpp\n{c.definition}\n```\n\n---\n\n"
 
-            out_path = self.out_dir / group_info['filename']
+            out_path = self.out_dir / group_info["filename"]
             out_path.write_text(md, encoding="utf-8")
             print(f"Generated {out_path} ({len(concepts)} concepts)")
 
     def _generate_index_file(self):
         """Generates the central API index mapping to all grouped concepts."""
-        md = f"{self.DEV_WARNING}\n"
-        md += "# Concepts API Reference {: #concepts-api-reference }\n\n"
+        md = "# Concepts API Reference {: #concepts-api-reference }\n\n"
         md += "This page serves as the central index for all C++20 concepts used across the library to enforce type safety and template constraints.\n\n---\n\n"
 
-        for group_key, group_info in self.GROUPS.items():
+        for group_key, group_info in self.groups.items():
             md += f"## {group_key} Concepts\n\n"
             md += f"- **[{group_info['title']}]({group_info['filename']})**: Full API reference.\n"
 
@@ -226,18 +258,23 @@ def _generate_index_file(self):
                 md += f"    - *(Documentation coming soon)*\n"
             else:
                 for c in concepts:
-                    desc_text = f": {c['brief']}" if c['brief'] else ""
-                    md += f"    - [`{c['name']}`]({group_info['filename']}#{c['anchor']}){desc_text}\n"
+                    desc_text = f": {c.brief}" if c.brief else ""
+                    md += f"    - [`{c.name}`]({group_info['filename']}#{c.anchor}){desc_text}\n"
             md += "\n---\n\n"
 
         index_path = self.out_dir / "concepts.md"
         index_path.write_text(md, encoding="utf-8")
         print(f"Generated {index_path} (API Index)")
 
+
 if __name__ == "__main__":
     parser = argparse.ArgumentParser()
-    parser.add_argument("--xml", default="xml", type=Path, help="Path to Doxygen XML output")
-    parser.add_argument("--out", default="docs/cpp-gl", type=Path, help="Path to MkDocs output folder")
+    parser.add_argument(
+        "--xml", default="xml", type=Path, help="Path to Doxygen XML output"
+    )
+    parser.add_argument(
+        "--out", default="docs/cpp-gl", type=Path, help="Path to MkDocs output folder"
+    )
     args = parser.parse_args()
 
     app = ConceptParser(args.xml, args.out)