refactor(docgen): improve template handling and output formatting

Author: wu-vincent

scripts/docgen/cppgen.py

@@ -47,7 +47,8 @@ def generate(base_dir: Path, debug: bool = True):
     #     doxygen.printStructure()
 
     # Prepare generator for future use (GeneratorAuto, SnippetGenerator)
-    base_generator = GeneratorBase("", ignore_errors=False, debug=debug)
+    template_dir = str(Path(__file__).parent / "templates" / "mkdoxy")
+    base_generator = GeneratorBase(template_dir, ignore_errors=False, debug=debug)
 
     generator = Generator(
         generatorBase=base_generator,
@@ -69,9 +70,3 @@ def generate(base_dir: Path, debug: bool = True):
     nodes = [node for node in root_node.children if node.kind == Kind.CLASS]
     generator.members(nodes, template_config)
     generator.classes(nodes, template_config)
-
-    for file in generator.fullDocFiles:
-        log.info(file)
-
-
-

scripts/docgen/generator.py

@@ -16,7 +16,11 @@ def save(self, path: str, output: str):
     def member(self, node: Node, config: dict = None):
         path = inflection.underscore(node.name_short) + ".md"
 
-        output = self.generatorBase.member(node, config)
+        output = ""
+        output += '---\n'
+        output += f'title: "{node.name_short}"\n'
+        output += '---\n\n'
+        output += self.generatorBase.member(node, config)
         self.save(path, output)
 
         if node.is_language or node.is_group or node.is_file or node.is_dir:

scripts/docgen/pygen.py

@@ -27,7 +27,7 @@ def render_object_docs(obj: Object, config: dict | None = None) -> str:
 
 
 def render_package_docs(package: str, config: dict | None = None) -> str:
-    config = config or dict(_rendering.default_config)
+    config = config or dict(rendering.default_config)
     parser = config["docstring_style"] and Parser(config["docstring_style"])
     extensions = griffe.load_extensions(StubOverloadExtension)
     loader = GriffeLoader(docstring_parser=parser, extensions=extensions)

scripts/docgen/templates/mkdoxy/member.jinja2

@@ -5,40 +5,24 @@ implements: True
 ---
 {% filter indent(config.get('indent_level', 0), True) %}
 
-# {{node.kind.value|title}} {{node.name_long}}
+## {{node.name_long}}
 {% if node.has_templateparams %}
 **template <{{node.templateparams}}>**
 {% endif %}
 
-
-[**{{node.base_name}}**]({{node.base_url}})
-{%- for parent in node.parents -%}
-{{'**>**'|indent(1, true)}} [**{{parent.name_long if node.is_group else parent.name_short}}**]({{parent.url}})
-{%- endfor %}
-
-{% if node.is_file and node.has_programlisting -%}
-[Go to the source code of this file]({{node.url_source}})
-{%- endif %}
-
-{{node.brief}}
-{%- if node.has_details -%}
-[More...](#detailed-description)
-{%- endif %}
-
-{% if node.has_includes -%}
-{%- for include in node.includes -%}
-* `#include {{include}}`
-{% endfor -%}
-{%- endif %}
-
 {% if node.has_base_classes %}
-Inherits the following classes:
+Bases:
 {%- for base in node.base_classes -%}
-{%- if base is string %} {{base}}{%- else %} [{{base.name_long}}]({{base.url}}){%- endif -%}
+{%- if base is string %} `{{base}}`{%- else %} [`{{base.name_long}}`]({{base.url}}){%- endif -%}
 {{ ', ' if not loop.last else '' }}
 {%- endfor -%}
 {%- endif %}
 
+{{node._brief.plain()}}
+{%- if node.has_details -%}
+[More...](#detailed-description)
+{%- endif %}
+
 {% if node.has_derived_classes %}
 Inherited by the following classes:
 {%- for derived in node.derived_classes -%}
@@ -86,25 +70,4 @@ Inherited by the following classes:
 {%- endfor -%}
 {%- endfor -%}
 
-{%- if node.has('public', ['define'], False) %}
-## Macro Definition Documentation
-
-{% for member in node.query('public', ['define'], False) -%}
-{{ templateMemDef.render({'config': {}, 'node': member, 'configMemDef': configMemDef}) }}
-{%- endfor -%}
-{%- endif %}
-
-{%- if node.has('public', ['friend'], False) -%}
-## Friends Documentation
-
-{% for member in node.query('public', ['friend'], False) -%}
-{{ templateMemDef.render({'config': {}, 'node': member, 'configMemDef': configMemDef}) }}
-{%- endfor %}
-{%- endif %}
-
-------------------------------
-{% if node.has_location -%}
-The documentation for this class was generated from the following file `{{node.location}}`
-{%- endif %}
-
 {% endfilter %}