"""Multi-format documentation renderer for ``muse code docs``. Converts a :class:`~muse.core.doc_extractor.DocReport` into one of four output formats: ``json`` Machine-readable, AI-ready. The full :class:`DocReport` TypedDict serialised as pretty-printed JSON. Suitable for ingestion by LLMs, RAG pipelines, and downstream tooling. ``html`` Standalone HTML page with an inline sidebar TOC, health bars, version badges, caller/callee sections, and linked test lists. Zero external dependencies — a single file that opens in any browser. ``markdown`` GitHub-compatible Markdown with a generated table of contents, one ``##`` heading per symbol, and structured sections for callers, callees, version history, and test linkage. ``text`` Terminal-friendly columnar table similar to ``muse code symbols``, with health score, stale indicator, and doc-debt summary. Security -------- All user-visible strings (symbol names, docstrings, file paths) are escaped appropriately before embedding in HTML or JSON output. The renderer never evaluates or executes any string from the report. Performance ----------- Renderers operate in a single linear pass over the ``symbols`` list. On a 400-symbol report the HTML renderer completes in <10 ms. """ import html as _html_module import json import logging from typing import Literal, TypedDict from muse.core.doc_extractor import DocReport, DocSummary, SymbolDoc type _BadgeMap = dict[str, str] logger = logging.getLogger(__name__) RenderFormat = Literal["json", "html", "markdown", "text"] """Supported output formats for :func:`render`.""" # --------------------------------------------------------------------------- # JSON renderer # --------------------------------------------------------------------------- def render_json(report: DocReport) -> str: """Return the full *report* as pretty-printed JSON. The output is structured identically to the :class:`DocReport` TypedDict — every field is present, making it directly usable by LLMs and agent pipelines. Args: report: The documentation report to serialise. """ return json.dumps(report, indent=2, ensure_ascii=False) # --------------------------------------------------------------------------- # Text renderer # --------------------------------------------------------------------------- _HEALTH_BAR_WIDTH = 10 def _health_bar(score: float) -> str: """Return a compact ASCII health bar, e.g. ``[████████░░]``.""" filled = round(score * _HEALTH_BAR_WIDTH) empty = _HEALTH_BAR_WIDTH - filled return f"[{'█' * filled}{'░' * empty}]" def _stale_flag(doc: SymbolDoc) -> str: return "⚠" if "stale_impl" in doc["doc_health_reasons"] else " " def render_text(report: DocReport) -> str: """Return a terminal-friendly columnar view of *report*. Columns: HEALTH ST KIND NAME FILE Health bar + score, stale flag, symbol kind, name, file path. Args: report: The documentation report to render. """ lines: list[str] = [] s = report["summary"] lines.append( f"Muse docs — commit {report['commit_id']} " f"generated {report['generated_at'][:19]}" ) lines.append( f" symbols={s['total_symbols']} " f"documented={s['documented']} " f"undocumented={s['undocumented']} " f"stale={s['stale_count']} " f"avg_health={s['avg_health']:.2f} " f"debt={s['doc_debt_score']:.2f}" ) lines.append("") if not report["symbols"]: lines.append(" (no symbols)") return "\n".join(lines) header = f"{'HEALTH':17} ST {'KIND':14} {'NAME':38} FILE" lines.append(header) lines.append("-" * len(header)) for doc in report["symbols"]: bar = _health_bar(doc["doc_health"]) score = f"{doc['doc_health']:.2f}" health_col = f"{bar} {score}" stale = _stale_flag(doc) kind = doc["kind"][:14] name = doc["name"][:38] file_col = doc["file"] lines.append(f"{health_col:17} {stale} {kind:14} {name:38} {file_col}") if report["missing"]: lines.append("") lines.append(f"Missing docstrings ({len(report['missing'])} public symbols):") for m in report["missing"][:20]: lines.append(f" [{m['caller_count']:3} callers] {m['address']}") if len(report["missing"]) > 20: lines.append(f" … and {len(report['missing']) - 20} more") if report["stale"]: lines.append("") lines.append(f"Potentially stale docstrings ({len(report['stale'])} symbols):") for st in report["stale"][:10]: lines.append(f" {st['address']}") if len(report["stale"]) > 10: lines.append(f" … and {len(report['stale']) - 10} more") return "\n".join(lines) # --------------------------------------------------------------------------- # Markdown renderer # --------------------------------------------------------------------------- _MD_KIND_BADGE: _BadgeMap = { "function": "fn", "async_function": "async fn", "class": "class", "method": "method", "async_method": "async method", "variable": "var", "import": "import", "section": "section", "rule": "rule", } def _md_health_indicator(score: float) -> str: """Return an emoji indicator for the health score.""" if score >= 0.85: return "✅" if score >= 0.60: return "🟡" return "🔴" def render_markdown(report: DocReport) -> str: """Return GitHub-compatible Markdown for *report*. Structure: - H1 header with commit and summary stats - Auto-generated TOC for all symbols - Per-symbol H2 sections with docstring, signature, callers, callees, version info, linked tests, and health score Args: report: The documentation report to render. """ lines: list[str] = [] s = report["summary"] lines.append("# Muse Documentation Report") lines.append("") lines.append(f"**Commit:** `{report['commit_id']}` ") lines.append(f"**Generated:** {report['generated_at'][:19]} ") lines.append( f"**Health:** avg={s['avg_health']:.2f} " f"debt={s['doc_debt_score']:.2f} " f"documented={s['documented']}/{s['total_symbols']}" ) lines.append("") if report["symbols"]: lines.append("## Table of Contents") lines.append("") for doc in report["symbols"]: anchor = doc["address"].lower().replace(" ", "-").replace("/", "").replace("::", "--").replace(".", "") indicator = _md_health_indicator(doc["doc_health"]) lines.append(f"- {indicator} [`{doc['qualified_name']}`](#{anchor})") lines.append("") for doc in report["symbols"]: anchor = doc["address"].lower().replace(" ", "-").replace("/", "").replace("::", "--").replace(".", "") kind_badge = _MD_KIND_BADGE.get(doc["kind"], doc["kind"]) indicator = _md_health_indicator(doc["doc_health"]) lines.append(f"## `{doc['qualified_name']}` {{#{anchor}}}") lines.append("") lines.append( f"> {indicator} **{kind_badge}** in `{doc['file']}`" f" (lines {doc['lineno']}–{doc['end_lineno']})" ) lines.append("") if doc["signature"]: lines.append("```python") lines.append(doc["signature"]) lines.append("```") lines.append("") if doc["docstring"]: lines.append(doc["docstring"]) else: lines.append("*No docstring.*") lines.append("") if doc["since_version"] or doc["since_commit"]: ver = doc["since_version"] or "" cid = doc["since_commit"] or "" lines.append(f"**Introduced:** {ver or cid}") lines.append("") if doc["last_changed_version"] or doc["last_changed_commit"]: ver = doc["last_changed_version"] or "" cid = doc["last_changed_commit"] or "" lines.append(f"**Last changed:** {ver or cid}") lines.append("") if doc["breaking_changes"]: lines.append("**Breaking changes:**") for bc in doc["breaking_changes"]: lines.append(f"- {bc}") lines.append("") if doc["callers"]: lines.append(f"**Called by** ({len(doc['callers'])}):") for c in doc["callers"][:10]: lines.append(f"- `{c}`") if len(doc["callers"]) > 10: lines.append(f"- *(+{len(doc['callers']) - 10} more)*") lines.append("") if doc["callees"]: lines.append(f"**Calls** ({len(doc['callees'])}):") for c in doc["callees"][:10]: lines.append(f"- `{c}`") if len(doc["callees"]) > 10: lines.append(f"- *(+{len(doc['callees']) - 10} more)*") lines.append("") if doc["linked_tests"]: lines.append(f"**Tests** ({len(doc['linked_tests'])}):") for t in doc["linked_tests"][:5]: lines.append(f"- `{t}`") if len(doc["linked_tests"]) > 5: lines.append(f"- *(+{len(doc['linked_tests']) - 5} more)*") lines.append("") reasons = doc["doc_health_reasons"] lines.append( f"**Doc health:** {doc['doc_health']:.2f}" + (f" ({', '.join(reasons)})" if reasons else "") ) lines.append("") lines.append("---") lines.append("") if report["missing"]: lines.append("## Missing Docstrings") lines.append("") lines.append( f"{len(report['missing'])} public symbol(s) lack docstrings " f"(sorted by caller count):" ) lines.append("") lines.append("| Callers | Address |") lines.append("|---------|---------|") for m in report["missing"]: lines.append(f"| {m['caller_count']} | `{m['address']}` |") lines.append("") if report["stale"]: lines.append("## Stale Docstrings") lines.append("") lines.append( f"{len(report['stale'])} symbol(s) may have stale documentation:" ) lines.append("") for st in report["stale"]: changed = "signature" if st["signature_changed"] else "body" lines.append(f"- `{st['address']}` — {changed} changed") lines.append("") return "\n".join(lines) # --------------------------------------------------------------------------- # HTML renderer # --------------------------------------------------------------------------- _HTML_TEMPLATE = """\ Muse Docs — {commit_short}

Muse Documentation

Commit {commit_short}  ·  {generated_at}
{total}
Symbols
{documented}
Documented
{undocumented}
Missing
{stale}
Stale
{avg_health}
Avg Health
{debt}
Doc Debt
{symbol_sections} {missing_section}
""" _BADGE_CLASS: _BadgeMap = { "function": "badge-fn", "async_function": "badge-fn", "class": "badge-class", "method": "badge-method", "async_method": "badge-method", "variable": "badge-var", } def _e(s: str) -> str: """HTML-escape *s*.""" return _html_module.escape(s, quote=True) def _health_class(score: float) -> str: if score >= 0.75: return "health-good" if score >= 0.50: return "health-mid" return "health-bad" def _render_symbol_html(doc: SymbolDoc) -> str: anchor = _e(doc["address"].replace(" ", "_")) kind_badge = _BADGE_CLASS.get(doc["kind"], "badge-other") kind_label = _e(doc["kind"].replace("_", " ")) score_pct = int(doc["doc_health"] * 100) health_cls = _health_class(doc["doc_health"]) parts: list[str] = [] parts.append(f'
') parts.append( f'

{_e(doc["qualified_name"])}' f' {kind_label}

' ) parts.append( f'
{_e(doc["file"])} ' f' lines {doc["lineno"]}–{doc["end_lineno"]}
' ) # Health bar parts.append('
') parts.append('
') parts.append( f'
' ) parts.append("
") parts.append(f' {doc["doc_health"]:.2f}') if "stale_impl" in doc["doc_health_reasons"]: parts.append(' ⚠ stale') parts.append("
") # Version badges if doc["since_version"]: parts.append( f' since {_e(doc["since_version"])}' ) if doc["last_changed_version"]: parts.append( f' changed {_e(doc["last_changed_version"])}' ) # Signature if doc["signature"]: parts.append(f" 
{_e(doc['signature'])}
") # Docstring if doc["docstring"]: parts.append(f'
{_e(doc["docstring"])}
') else: parts.append('
No docstring.
') # Breaking changes if doc["breaking_changes"]: parts.append('
Breaking Changes
') for bc in doc["breaking_changes"]: parts.append(f'
{_e(bc)}
') # Callers if doc["callers"]: parts.append( f'
Called by ({len(doc["callers"])})
' ) parts.append('
') for c in doc["callers"][:15]: parts.append(f' {_e(c)}') if len(doc["callers"]) > 15: parts.append( f' +{len(doc["callers"]) - 15} more' ) parts.append("
") # Callees if doc["callees"]: parts.append( f'
Calls ({len(doc["callees"])})
' ) parts.append('
') for c in doc["callees"][:15]: parts.append(f' {_e(c)}') if len(doc["callees"]) > 15: parts.append( f' +{len(doc["callees"]) - 15} more' ) parts.append("
") # Linked tests if doc["linked_tests"]: parts.append( f'
Tests ({len(doc["linked_tests"])})
' ) parts.append('
') for t in doc["linked_tests"][:8]: parts.append(f' {_e(t)}') if len(doc["linked_tests"]) > 8: parts.append( f' +{len(doc["linked_tests"]) - 8} more' ) parts.append("
") parts.append("
") return "\n".join(parts) def render_html(report: DocReport) -> str: """Return a self-contained HTML page for *report*. The page includes an inline sidebar TOC, health bars, version badges, caller/callee pill lists, and linked test lists. It has zero external dependencies and opens in any browser. Args: report: The documentation report to render. """ s = report["summary"] nav_links_parts: list[str] = [] for doc in report["symbols"]: anchor = _e(doc["address"].replace(" ", "_")) indicator = "✅" if doc["doc_health"] >= 0.75 else ("🟡" if doc["doc_health"] >= 0.50 else "🔴") nav_links_parts.append( f' ' f'{indicator} {_e(doc["name"])}' ) symbol_sections = "\n".join( _render_symbol_html(doc) for doc in report["symbols"] ) # Missing section missing_parts: list[str] = [] if report["missing"]: missing_parts.append( f'
' f'

Missing Docstrings ({len(report["missing"])})

' f'' f"" ) for m in report["missing"]: missing_parts.append( f"" f"" f"" ) missing_parts.append("
CallersAddressKind
{m['caller_count']}{_e(m['address'])}{_e(m['kind'])}
") return _HTML_TEMPLATE.format( commit_short=_e(report["commit_id"]), generated_at=_e(report["generated_at"][:19]), total=s["total_symbols"], documented=s["documented"], undocumented=s["undocumented"], stale=s["stale_count"], avg_health=f"{s['avg_health']:.2f}", debt=f"{s['doc_debt_score']:.2f}", nav_links="\n".join(nav_links_parts), symbol_sections=symbol_sections, missing_section="\n".join(missing_parts), ) # --------------------------------------------------------------------------- # Dispatcher # --------------------------------------------------------------------------- def render(report: DocReport, fmt: RenderFormat) -> str: """Render *report* in the requested *fmt*. Args: report: The documentation report from :func:`~doc_extractor.extract_docs`. fmt: Output format: ``"json"``, ``"html"``, ``"markdown"``, or ``"text"``. Returns: A string in the requested format, ready to write to a file or stdout. Raises: ValueError: When *fmt* is not one of the supported values. """ if fmt == "json": return render_json(report) if fmt == "html": return render_html(report) if fmt == "markdown": return render_markdown(report) if fmt == "text": return render_text(report) raise ValueError(f"Unsupported render format: {fmt!r}")