feat: markdown API documentation rendering

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

src/auto_reverse/doc/markdown.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from auto_reverse.models import EndpointRecord
+
+
+def render_markdown(records: list[EndpointRecord], title: str) -> str:
+    groups: dict[str, list[EndpointRecord]] = defaultdict(list)
+    for rec in records:
+        groups[rec.tag or "General"].append(rec)
+
+    lines = [f"# {title}", ""]
+    for tag in sorted(groups):
+        lines.append(f"## {tag}")
+        lines.append("")
+        for rec in sorted(groups[tag], key=lambda r: r.signature.path_template):
+            sig = rec.signature
+            lines.append(f"### `{sig.method} {sig.path_template}`")
+            if rec.summary:
+                lines.append(f"**{rec.summary}**")
+            if rec.description:
+                lines.append("")
+                lines.append(rec.description)
+            lines.append(f"\n_Seen {rec.sample_count} time(s)._")
+            lines.append("")
+    return "\n".join(lines)

tests/test_markdown.py

@@ -0,0 +1,31 @@
+from auto_reverse.doc.markdown import render_markdown
+from auto_reverse.models import EndpointRecord, Signature
+
+
+def _rec(method, template, **kw):
+    rec = EndpointRecord(signature=Signature(method, "ex.com", template, "2xx"))
+    for k, v in kw.items():
+        setattr(rec, k, v)
+    return rec
+
+
+def test_renders_heading_and_endpoints():
+    md = render_markdown([_rec("GET", "/api/users", summary="List users")], title="ex.com API")
+    assert "# ex.com API" in md
+    assert "`GET /api/users`" in md
+    assert "List users" in md
+
+
+def test_groups_by_tag():
+    records = [
+        _rec("GET", "/api/users", tag="Users"),
+        _rec("GET", "/api/cart", tag="Cart"),
+    ]
+    md = render_markdown(records, title="x")
+    assert "## Users" in md
+    assert "## Cart" in md
+
+
+def test_untagged_go_under_general():
+    md = render_markdown([_rec("GET", "/api/x")], title="x")
+    assert "## General" in md