feat: Implement C templates (prototype)

Author: pawamoy

README.md

@@ -11,3 +11,22 @@ A C handler for mkdocstrings.
 This project is available to sponsors only, through my Insiders program.
 See Insiders [explanation](https://mkdocstrings.github.io/c/insiders/)
 and [installation instructions](https://mkdocstrings.github.io/c/insiders/installation/).
+
+## Usage
+
+With the following header file:
+
+```c title="hello.h"
+--8<-- "docs/snippets/hello.h"
+```
+
+Generate docs for this file with this instruction in one of your Markdown page:
+
+```md
+::: path/to/hello.h
+```
+
+This will generate the following HTML:
+
+::: docs/snippets/hello.h
+    handler: c

docs/snippets/hello.h

@@ -0,0 +1,21 @@
+#ifndef HELLO_H
+#define HELLO_H // Header guard for `hello.h`.
+
+// Some macro that holds something.
+#define SOME_MACRO 123
+
+// Pointer to an integer.
+typedef const int* foo_t;
+
+/*
+ * My cool function that does something **cool**!
+ * 
+ * @param[in] x Input thingy!
+ * @param[out] y Output thingy!
+ * @param z Some other thing
+ */
+void foo(int* x, int* y, foo_t z);
+
+const foo_t x = ((foo_t) 0); // Random NULL pointer
+
+#endif

mkdocs.yml

@@ -116,6 +116,10 @@ plugins:
 - coverage
 - mkdocstrings:
     handlers:
+      c:
+        options:
+          show_symbol_type_heading: true
+          show_symbol_type_toc: true
       python:
         import:
         - https://docs.python.org/3/objects.inv

pyproject.toml

@@ -29,7 +29,8 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "mkdocstrings>=0.18",
+    "mkdocstrings>=0.25",
+    "pycparser>=2.20",
 ]
 
 [project.urls]

src/mkdocstrings_handlers/c/handler.py

@@ -161,12 +161,12 @@ def extract_macros(code: str) -> tuple[list[Macro], str]:
     return macros, "\n".join(extracted)
 
 
-class InOut(Enum):
+class InOut(str, Enum):
     """Enumeration for parameter direction."""
 
-    UNSPECIFIED = 0
-    IN = 1
-    OUT = 2
+    UNSPECIFIED = "unspecified"
+    IN = "in"
+    OUT = "out"
 
 
 @dataclass
@@ -320,13 +320,13 @@ class CodeDoc:
     typedefs: dict[str, DocType]
 
 
-class TypeDecl(Enum):
+class TypeDecl(str, Enum):
     """Enumeration for type declarations."""
 
-    NORMAL = 0
-    POINTER = 1
-    ARRAY = 2
-    FUNCTION = 3
+    NORMAL = "normal"
+    POINTER = "pointer"
+    ARRAY = "array"
+    FUNCTION = "function"
 
 
 @dataclass
@@ -413,6 +413,18 @@ def tp_ref_to_str(ref: TypeRef, qualname: str) -> str:
     return f"{ret} (*{qualname})({', '.join(params)})"
 
 
+def typedef_to_str(decl: DocType) -> str:
+    """Convert a typedef to a string.
+
+    Parameters:
+        decl: The typedef to convert.
+
+    Returns:
+        The string representation of the typedef.
+    """
+    return tp_ref_to_str(decl.tp, decl.name)
+
+
 def desc(doc: Docstring | None) -> str:
     """Get the description from a docstring.
 
@@ -441,9 +453,9 @@ def lookup_type_html(data: CodeDoc, tp: TypeRef, *, name: str | None = None) ->
     """
     tp_str = ""
 
-    for name, doctype in data.typedefs.items():
+    for type_name, doctype in data.typedefs.items():
         if doctype.tp == tp:
-            tp_str = f'<a href="#type-{name}">{name}</a>'
+            tp_str = f'<a href="#type-{type_name}">{type_name}</a>'
 
     return f'<code>{tp_str or tp_ref_to_str(tp, name or "unknown")}</code>'
 
@@ -469,6 +481,8 @@ class CHandler(BaseHandler):
     default_config: ClassVar[dict] = {
         "show_root_heading": False,
         "show_root_toc_entry": True,
+        "show_symbol_type_heading": True,
+        "show_symbol_type_toc_entry": True,
         "heading_level": 2,
     }
     """The default configuration options.
@@ -480,7 +494,7 @@ class CHandler(BaseHandler):
     **`heading_level`** | `int` | The initial heading level to use. | `2`
     """
 
-    def collect(self, identifier: str, config: MutableMapping[str, Any]) -> CollectorItem:  # noqa: ARG002
+    def collect(self, identifier: str, config: MutableMapping[str, Any]) -> CollectorItem:
         """Collect data given an identifier and selection configuration.
 
         In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into
@@ -496,6 +510,9 @@ def collect(self, identifier: str, config: MutableMapping[str, Any]) -> Collecto
         Returns:
             Anything you want, as long as you can feed it to the `render` method.
         """
+        if config.get("fallback", False):
+            raise CollectionError("Not loading additional headers during fallback")
+
         source = Path(identifier).read_text(encoding="utf-8")
         comments_list, source = extract_comments(source)
         macros_list, source = extract_macros(source)
@@ -573,7 +590,7 @@ def collect(self, identifier: str, config: MutableMapping[str, Any]) -> Collecto
     # def get_templates_dir(self, handler: str | None = None) -> Path:
     #     return Path.cwd()
 
-    def render(self, data: CodeDoc, config: Mapping[str, Any]) -> str:  # noqa: ARG002
+    def render(self, data: CodeDoc, config: Mapping[str, Any]) -> str:
         """Render a template using provided data and configuration options.
 
         Parameters:
@@ -584,13 +601,15 @@ def render(self, data: CodeDoc, config: Mapping[str, Any]) -> str:  # noqa: ARG0
         Returns:
             The rendered template as HTML.
         """
-        # final_config = {**self.default_config, **config}
-        # heading_level = final_config["heading_level"]
-        # template = self.env.get_template(f"{data...}.html.jinja")
-        # return template.render(
-        #     **{"config": final_config, data...: data, "heading_level": heading_level, "root": True},
-        # )
-        raise PluginError("Implement me!")
+        final_config = {**self.default_config, **config}
+        heading_level = final_config["heading_level"]
+        template = self.env.get_template("header.html.jinja")
+        return template.render(
+            config=final_config,
+            header=data,
+            heading_level=heading_level,
+            root=True,
+        )
 
     def update_env(self, md: Markdown, config: dict) -> None:
         """Update the Jinja environment with any custom settings/filters/options for this handler.
@@ -604,6 +623,9 @@ def update_env(self, md: Markdown, config: dict) -> None:
         self.env.trim_blocks = True
         self.env.lstrip_blocks = True
         self.env.keep_trailing_newline = False
+        self.env.filters["typedef_to_str"] = typedef_to_str
+        self.env.filters["lookup_type_html"] = lookup_type_html
+        self.env.filters["zip"] = zip
 
 
 def get_handler(

src/mkdocstrings_handlers/c/templates/material/_base/function.html.jinja

@@ -0,0 +1,36 @@
+{% filter heading(
+    heading_level,
+    id=func.name,
+    class="doc doc-heading",
+    toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + func.name,
+) %}
+    {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>{% endif %}
+    {{ header | lookup_type_html(func.ret) | safe }}
+    <code>{{ func.name }}</code>
+    {% if func.args %}
+        (
+        {%- for param in func.args %}
+            {{ header | lookup_type_html(param.tp, name=param.name) | safe }}<code>{{ param.name }}</code>{{ ", " if not loop.last else "" }}
+        {% endfor -%}
+        )
+    {% else %}
+        void
+    {% endif %}
+{% endfilter %}
+{{ func.doc.desc | default("No description provided.") | convert_markdown(func.name) }}
+{% if func.doc and func.doc.params %}
+    <table>
+        <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Description</th>
+        </tr>
+        {% for doc, param in func.doc.params | zip(func.args) %}
+            <tr>
+                <td>{{ doc.name }}</td>
+                <td>{{ header | lookup_type_html(param.tp, name=param.name) | safe }}{{ "" if doc.in_out == "unspecified" else "[" ~ doc.in_out ~ "]" }}</td>
+                <td>{{ doc.desc | default("No description provided.") | convert_markdown(func.name) }}</td>
+            </tr>
+        {% endfor %}
+    </table>
+{% endif %}

src/mkdocstrings_handlers/c/templates/material/_base/global_var.html.jinja

@@ -0,0 +1,11 @@
+{% filter heading(
+    heading_level,
+    id=var.name,
+    class="doc doc-heading",
+    toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-var"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + var.name,
+) %}
+    {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-var"></code>{% endif %}
+    {{ header | lookup_type_html(var.tp) | safe }}
+    <code>{{ var.name }}</code>
+{% endfilter %}
+{{ var.doc.desc | default("No description provided.") | convert_markdown(var.name) }}

src/mkdocstrings_handlers/c/templates/material/_base/header.html.jinja

@@ -0,0 +1,23 @@
+{% if header.macros %}
+    {% for macro in header.macros %}
+        {% include "macro.html.jinja" with context %}
+    {% endfor %}
+{% endif %}
+
+{% if header.typedefs %}
+    {% for tp in header.typedefs.values() %}
+        {% include "typedef.html.jinja" with context %}
+    {% endfor %}
+{% endif %}
+
+{% if header.global_vars %}
+    {% for var in header.global_vars %}
+        {% include "global_var.html.jinja" with context %}
+    {% endfor %}
+{% endif %}
+
+{% if header.functions %}
+    {% for func in header.functions %}
+        {% include "function.html.jinja" with context %}
+    {% endfor %}
+{% endif %}

src/mkdocstrings_handlers/c/templates/material/_base/macro.html.jinja

@@ -0,0 +1,11 @@
+{% filter heading(
+    heading_level,
+    id=macro.name,
+    class="doc doc-heading",
+    toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-macro"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + macro.name,
+) %}
+    {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-macro"></code>{% endif %}
+    <code>{{ macro.name }}</code>
+    {% if macro.content %}<code>{{ macro.content }}</code>{% endif %}
+{% endfilter %}
+{{ macro.doc.desc | default("No description provided.") | convert_markdown(macro.name) }}

src/mkdocstrings_handlers/c/templates/material/_base/typedef.html.jinja

@@ -0,0 +1,11 @@
+{% filter heading(
+    heading_level,
+    id=tp.name,
+    class="doc doc-heading",
+    toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-typedef"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + tp.name,
+) %}
+    {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-typedef"></code>{% endif %}
+    <code>{{ tp.name }}</code>
+    <code>{{ tp | typedef_to_str }}</code>
+{% endfilter %}
+{{ tp.doc.desc | default("No description provided.") | convert_markdown(tp.name) }}