docs: update cpp reference links

Author: wu-vincent

content/reference/cpp/index.mdx

@@ -2,13 +2,13 @@
 import logging
 from pathlib import Path
 
+from generator import Generator, BaseGenerator
 from mkdoxy.cache import Cache
 from mkdoxy.constants import Kind
 from mkdoxy.doxygen import Doxygen
 from mkdoxy.doxyrun import DoxygenRun
 from mkdoxy.generatorBase import GeneratorBase
 from mkdoxy.xml_parser import XmlParser
-from generator import Generator
 
 logging.basicConfig()
 log: logging.Logger = logging.getLogger("mkdocs")
@@ -29,7 +29,9 @@ def generate(base_dir: Path, debug: bool = True):
         "STRIP_FROM_INC_PATH": str(base_dir / "include"),
     }
 
-    runner = DoxygenRun('doxygen', str(base_dir / "include" / "endstone"), str(temp_dir), config, "")
+    runner = DoxygenRun(
+        "doxygen", str(base_dir / "include" / "endstone"), str(temp_dir), config, ""
+    )
     if runner.checkAndRun():
         log.info("  -> generating Doxygen files")
     else:
@@ -48,7 +50,7 @@ def generate(base_dir: Path, debug: bool = True):
 
     # Prepare generator for future use (GeneratorAuto, SnippetGenerator)
     template_dir = str(Path(__file__).parent / "templates" / "mkdoxy")
-    base_generator = GeneratorBase(template_dir, ignore_errors=False, debug=debug)
+    base_generator = BaseGenerator(template_dir, ignore_errors=False, debug=debug)
 
     generator = Generator(
         generatorBase=base_generator,

scripts/docgen/_rendering.py

@@ -1,17 +1,26 @@
 import ast
-
-from griffe import Class, Extension, Function, Inspector, Kind, ObjectNode, Visitor, typing_overload
 from typing import Any
 
+from griffe import (
+    Class,
+    Extension,
+    Function,
+    Inspector,
+    Kind,
+    ObjectNode,
+    Visitor,
+    typing_overload,
+)
+
 
 class StubOverloadExtension(Extension):
     def on_function_instance(
-            self,
-            *,
-            node: ast.AST | ObjectNode,
-            func: Function,
-            agent: Visitor | Inspector,
-            **kwargs: Any,
+        self,
+        *,
+        node: ast.AST | ObjectNode,
+        func: Function,
+        agent: Visitor | Inspector,
+        **kwargs: Any,
     ) -> None:
         """
         Fix overloads with implementations in stub files not detected

scripts/docgen/cppgen.py

@@ -0,0 +1,108 @@
+import re
+from typing import Sequence
+
+from griffe import DocstringFunction, DocstringSectionFunctions, Function
+
+
+def do_heading(
+    content: str, heading_level: int, role: str | None = None, **attributes: str
+) -> str:
+    """Render a Markdown heading.
+
+    Arguments:
+        content: The HTML within the heading.
+        heading_level: The level of heading (e.g. 3 -> `###`).
+        role: An optional role for the object bound to this heading.
+        **attributes: Any extra attributes of the heading.
+    """
+
+    heading = f"\n{'#' * heading_level}"
+
+    if role:
+        heading += f' <code className="doc-symbol doc-symbol-{role}"/>'
+
+    heading += f" {content}"
+
+    if "id" in attributes:
+        heading += f" [#{attributes['id']}]"
+
+    heading += "\n\n"
+    return heading
+
+
+def do_as_functions_section(
+    functions: Sequence[Function],
+    *,
+    check_public: bool = True,
+) -> DocstringSectionFunctions:
+    """Build a functions section from a list of functions.
+
+    Parameters:
+        functions: The functions to build the section from.
+        check_public: Whether to check if the function is public.
+
+    Returns:
+        A functions docstring section.
+    """
+    value = []
+    for function in functions:
+        if (check_public and not function.is_public) or (function.name == "__init__"):
+            continue
+
+        if function.overloads:
+            value.append(
+                DocstringFunction(
+                    name=function.name,
+                    description="\n".join(
+                        list(
+                            dict.fromkeys(
+                                [
+                                    overload.docstring.value.split("\n", 1)[0]
+                                    if overload.docstring
+                                    else ""
+                                    for overload in function.overloads
+                                ]
+                            )
+                        )
+                    ),
+                )
+            )
+
+        else:
+            value.append(
+                DocstringFunction(
+                    name=function.name,
+                    description=function.docstring.value.split("\n", 1)[0]
+                    if function.docstring
+                    else "",
+                )
+            )
+
+    return DocstringSectionFunctions(value)
+
+
+def do_format_refid(refid: str) -> str:
+    """
+    Examples:
+      'classendstone_1_1_dimension'      -> 'dimension'
+      'classfoo_1_1bar_1_1Baz'           -> 'baz'
+      'structmy__type'                    -> 'my_type'
+      'classns_1_1vector_3_01T_01_4'     -> 'vector'
+    """
+    if not refid:
+        return ""
+    # drop leading kind
+    s = re.sub(r"^(class|struct|union|interface|namespace|enum|file)", "", refid)
+    # take last namespace component
+    s = re.split(r"(?:_1_1)+", s)[-1]
+    # remove any stray leading underscores left by the split (e.g. '_dimension')
+    s = s.lstrip("_")
+    # remove template-argument encoding (anything after '_3')
+    s = re.sub(r"_[3-9].*$", "", s)
+    # fix doxygen’s doubled-underscore escape
+    s = s.replace("__", "_")
+
+    if s == "u_u_i_d":
+        s = "uuid"
+
+    return s.lower()

scripts/docgen/extension.py

@@ -1,25 +1,105 @@
+import logging
 import os
 
+import filters
+import mkdoxy
+from jinja2 import BaseLoader, Environment, Template
+from mkdocs import exceptions
 from mkdocs.structure import files
+from mkdoxy.filters import use_code_language
 from mkdoxy.generatorAuto import GeneratorAuto
+from mkdoxy.generatorBase import GeneratorBase
 from mkdoxy.node import Node
-import inflection
+from mkdoxy.utils import parseTemplateFile
+
+from scripts.docgen.filters import do_format_refid
+
+log: logging.Logger = logging.getLogger("mkdocs")
+
+
+class BaseGenerator(GeneratorBase):
+    def __init__(
+        self, templateDir: str = "", ignore_errors: bool = False, debug: bool = False
+    ):
+        """! Constructor.
+        @details
+        @param templateDir (str): Path to the directory with custom templates (default: "")
+        @param ignore_errors (bool): If True, errors will be ignored (default: False)
+        @param debug (bool): If True, debug messages will be printed (default: False)
+        """
+
+        """! Constructor.
+        @details
+        @param templateDir (str): Path to the directory with custom templates (default: "")
+        @param ignore_errors (bool): If True, errors will be ignored (default: False)
+        @param debug (bool): If True, debug messages will be printed (default: False)
+        """
+
+        self.debug: bool = debug  # if True, debug messages will be printed
+        self.templates: dict[str, Template] = {}
+        self.metaData: dict[str, list[str]] = {}
+
+        environment = Environment(loader=BaseLoader())
+        environment.filters["use_code_language"] = use_code_language
+        environment.filters["format_refid"] = do_format_refid
+        # code from https://github.com/daizutabi/mkapi/blob/master/mkapi/core/renderer.py#L29-L38
+        path = os.path.join(os.path.dirname(mkdoxy.__file__), "templates")
+        ENDING = (".jinja2", ".j2", ".jinja")
+        for fileName in os.listdir(path):
+            filePath = os.path.join(path, fileName)
+
+            # accept any case of the file ending
+            if fileName.lower().endswith(ENDING):
+                with open(filePath, "r") as file:
+                    name = os.path.splitext(fileName)[0]
+                    fileTemplate, metaData = parseTemplateFile(file.read())
+                    self.templates[name] = environment.from_string(fileTemplate)
+                    self.metaData[name] = metaData
+            else:
+                log.error(
+                    f"Trying to load unsupported file '{filePath}'. Supported file ends with {ENDING}."
+                    f"Look at documentation: https://mkdoxy.kubaandrysek.cz/usage/#custom-jinja-templates."
+                )
+
+        # test if templateDir is existing
+        if templateDir:
+            if not os.path.exists(templateDir):
+                raise exceptions.ConfigurationError(
+                    f"Custom template directory '{templateDir}' does not exist."
+                )
+            # load custom templates and overwrite default templates - if they exist
+            for fileName in os.listdir(templateDir):
+                filePath = os.path.join(templateDir, fileName)
+                if fileName.lower().endswith(ENDING):
+                    with open(filePath, "r") as file:
+                        name = os.path.splitext(fileName)[0]
+                        fileTemplate, metaData = parseTemplateFile(file.read())
+                        self.templates[name] = environment.from_string(fileTemplate)
+                        self.metaData[name] = metaData
+                        log.info(f"Overwriting template '{name}' with custom template.")
+                else:
+                    log.error(
+                        f"Trying to load unsupported file '{filePath}'. Supported file ends with {ENDING}."
+                        f"Look at documentation: https://mkdoxy.kubaandrysek.cz/usage/#custom-jinja-templates."
+                    )
 
 
 class Generator(GeneratorAuto):
     def save(self, path: str, output: str):
         rel_path = os.path.join(self.apiPath, path)
-        self.fullDocFiles.append(files.File(rel_path, self.tempDoxyDir, self.siteDir, self.useDirectoryUrls))
+        self.fullDocFiles.append(
+            files.File(rel_path, self.tempDoxyDir, self.siteDir, self.useDirectoryUrls)
+        )
         with open(os.path.join(self.siteDir, rel_path), "w", encoding="utf-8") as file:
             file.write(output)
 
     def member(self, node: Node, config: dict = None):
-        path = inflection.underscore(node.name_short) + ".mdx"
+        path = filters.do_format_refid(node.refid) + ".mdx"
 
         output = ""
-        output += '---\n'
+        output += "---\n"
         output += f'title: "{node.name_short}"\n'
-        output += '---\n\n'
+        output += "---\n\n"
         output += self.generatorBase.member(node, config)
         self.save(path, output)
 
@@ -30,8 +110,8 @@ def classes(self, nodes: [Node], config: dict = None):
         path = "index.mdx"
 
         output = ""
-        output += '---\n'
+        output += "---\n"
         output += f'asIndexPage: true"\n'
-        output += '---\n\n'
+        output += "---\n\n"
         output += self.generatorBase.classes(nodes, config)
         self.save(path, output)

scripts/docgen/filters.py

@@ -1,16 +1,19 @@
 import argparse
 from pathlib import Path
-import pygen
+
 import cppgen
+import pygen
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser()
-    parser.add_argument("base_dir", type=Path, help="Base directory for code generation")
+    parser.add_argument(
+        "base_dir", type=Path, help="Base directory for code generation"
+    )
     parser.add_argument(
         "--language",
         type=str,
         choices=["python", "cpp"],
-        help="Language to generate code for (default: both)"
+        help="Language to generate code for (default: both)",
     )
     args = parser.parse_args()