reportsmith 0.2.0__tar.gz → 0.3.0__tar.gz

{reportsmith-0.2.0/reportsmith.egg-info → reportsmith-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: reportsmith
-Version: 0.2.0
+Version: 0.3.0
 Summary: A small, dependency-free library for building reports and exporting them to Markdown, HTML, LaTeX and PDF
 Author: Michal Stojke
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/mstojke/reportsmith
-Project-URL: Documentation, https://github.com/mstojke/reportsmith/blob/main/docs/user-guide.md
+Project-URL: Documentation, https://reportsmith.readthedocs.io/en/latest/index.html
 Project-URL: Changelog, https://github.com/mstojke/reportsmith/blob/main/CHANGELOG.md
 Project-URL: Issues, https://github.com/mstojke/reportsmith/issues
 Keywords: report,markdown,html,latex,pdf,export,document
@@ -35,6 +35,8 @@ A small, dependency-free Python library for building reports programmatically an
 ## Features
 
 - Fluent builder API with chainable methods and nested sections (`with report.section(...)`)
+- Table of contents in every format: linked lists in Markdown/HTML, `\tableofcontents` in LaTeX, clickable entries with page numbers in PDF
+- Tables straight from data: lists of dicts, CSV files, or pandas DataFrames, with number formatting, missing-value placeholders, and automatic right-alignment of numeric columns
 - Elements: headings, paragraphs, tables (with alignment and captions), bullet/numbered lists (nestable), code blocks, block quotes, images, horizontal rules, and format-specific raw passthrough
 - Inline formatting helpers: `bold()`, `italic()`, `code()`, `link()` — render correctly in both formats
 - Correct escaping everywhere: HTML entities, Markdown table pipes, code fences that widen when the source contains ` ``` `
@@ -57,6 +59,7 @@ Or just copy the `reportsmith/` package into your project — it has no dependen
 from reportsmith import Report, bold, link
 
 report = Report("Q3 Sales Report", author="Jane Doe", subtitle="Quarterly summary")
+report.toc()                         # table of contents
 
 with report.section("Overview") as s:
     s.paragraph(["Revenue was ", bold("up 12%"), " quarter over quarter."])
@@ -116,9 +119,11 @@ Builder methods (all chainable, also available on sections):
 | `code(source, language="")` | Fenced/`<pre>` code block |
 | `bullet_list(items)` / `numbered_list(items)` | List; items may be text or a nested `ListElement` |
 | `table(headers, rows, caption="", align=None)` | Table; `align` entries are `"left"`, `"center"`, `"right"` |
+| `table_from_records(records)` / `table_from_csv(source)` / `table_from_dataframe(df)` | Table built from data; options `columns`, `headers`, `formats`, `missing`, `align`, `caption` |
 | `image(src, alt="", title="")` | Image |
 | `horizontal_rule()` | Rule |
 | `raw(content, format="both")` | Verbatim content for `"markdown"`, `"html"`, `"latex"`, or `"both"` (Markdown + HTML) |
+| `toc(title="Contents", depth=3)` | Table of contents for the whole report; `depth` 1–5 sets how many heading levels are listed |
 | `add(element)` | Any pre-built element |
 
 Anywhere text is accepted you may pass a plain string or a list mixing strings with `bold()`, `italic()`, `code()`, and `link(text, href)` spans.
@@ -133,7 +138,7 @@ Anywhere text is accepted you may pass a plain string or a list mixing strings w
 
 ## Running tests
 
-The test suite (151 tests) lives in `tests/`:
+The test suite (256 tests) lives in `tests/`:
 
 ```bash
 python -m pytest

{reportsmith-0.2.0 → reportsmith-0.3.0}/README.md

@@ -5,6 +5,8 @@ A small, dependency-free Python library for building reports programmatically an
 ## Features
 
 - Fluent builder API with chainable methods and nested sections (`with report.section(...)`)
+- Table of contents in every format: linked lists in Markdown/HTML, `\tableofcontents` in LaTeX, clickable entries with page numbers in PDF
+- Tables straight from data: lists of dicts, CSV files, or pandas DataFrames, with number formatting, missing-value placeholders, and automatic right-alignment of numeric columns
 - Elements: headings, paragraphs, tables (with alignment and captions), bullet/numbered lists (nestable), code blocks, block quotes, images, horizontal rules, and format-specific raw passthrough
 - Inline formatting helpers: `bold()`, `italic()`, `code()`, `link()` — render correctly in both formats
 - Correct escaping everywhere: HTML entities, Markdown table pipes, code fences that widen when the source contains ` ``` `
@@ -27,6 +29,7 @@ Or just copy the `reportsmith/` package into your project — it has no dependen
 from reportsmith import Report, bold, link
 
 report = Report("Q3 Sales Report", author="Jane Doe", subtitle="Quarterly summary")
+report.toc()                         # table of contents
 
 with report.section("Overview") as s:
     s.paragraph(["Revenue was ", bold("up 12%"), " quarter over quarter."])
@@ -86,9 +89,11 @@ Builder methods (all chainable, also available on sections):
 | `code(source, language="")` | Fenced/`<pre>` code block |
 | `bullet_list(items)` / `numbered_list(items)` | List; items may be text or a nested `ListElement` |
 | `table(headers, rows, caption="", align=None)` | Table; `align` entries are `"left"`, `"center"`, `"right"` |
+| `table_from_records(records)` / `table_from_csv(source)` / `table_from_dataframe(df)` | Table built from data; options `columns`, `headers`, `formats`, `missing`, `align`, `caption` |
 | `image(src, alt="", title="")` | Image |
 | `horizontal_rule()` | Rule |
 | `raw(content, format="both")` | Verbatim content for `"markdown"`, `"html"`, `"latex"`, or `"both"` (Markdown + HTML) |
+| `toc(title="Contents", depth=3)` | Table of contents for the whole report; `depth` 1–5 sets how many heading levels are listed |
 | `add(element)` | Any pre-built element |
 
 Anywhere text is accepted you may pass a plain string or a list mixing strings with `bold()`, `italic()`, `code()`, and `link(text, href)` spans.
@@ -103,7 +108,7 @@ Anywhere text is accepted you may pass a plain string or a list mixing strings w
 
 ## Running tests
 
-The test suite (151 tests) lives in `tests/`:
+The test suite (256 tests) lives in `tests/`:
 
 ```bash
 python -m pytest

{reportsmith-0.2.0 → reportsmith-0.3.0}/pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
 
 [project.urls]
 Homepage = "https://github.com/mstojke/reportsmith"
-Documentation = "https://github.com/mstojke/reportsmith/blob/main/docs/user-guide.md"
+Documentation = "https://reportsmith.readthedocs.io/en/latest/index.html"
 Changelog = "https://github.com/mstojke/reportsmith/blob/main/CHANGELOG.md"
 Issues = "https://github.com/mstojke/reportsmith/issues"
 

{reportsmith-0.2.0 → reportsmith-0.3.0}/reportsmith/__init__.py

@@ -29,6 +29,7 @@ from .elements import (
     Raw,
     Section,
     Table,
+    TableOfContents,
 )
 from .report import Report
 from .renderers.markdown import MarkdownRenderer
@@ -36,7 +37,7 @@ from .renderers.html import HtmlRenderer
 from .renderers.pdf import PdfRenderer
 from .renderers.latex import LatexRenderer
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "Report",
@@ -44,6 +45,7 @@ __all__ = [
     "Heading",
     "Paragraph",
     "Table",
+    "TableOfContents",
     "ListElement",
     "CodeBlock",
     "Image",

reportsmith-0.3.0/reportsmith/data.py

@@ -0,0 +1,214 @@
+"""Build tables from structured data: records, CSV files and DataFrames.
+
+pandas is never imported: DataFrames are read through their public
+``columns`` / ``itertuples()`` interface, so reportsmith stays
+dependency-free and works with any DataFrame-like object.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import numbers
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Any, Callable, Iterable, Optional, Sequence, Union
+
+from .inline import Inline, TextLike
+
+if TYPE_CHECKING:
+    from .elements import Table
+
+#: A format string such as ``"{:,.2f}"`` or a callable returning cell text.
+CellFormat = Union[str, Callable[[Any], TextLike]]
+#: One format for every numeric cell, or a per-column mapping.
+Formats = Union[CellFormat, Mapping[Any, CellFormat], None]
+#: Display headers, either one per selected column or a key -> label mapping.
+Headers = Union[Sequence[TextLike], Mapping[Any, TextLike], None]
+
+_INT_RE = re.compile(r"[+-]?(?:0|[1-9]\d*)")
+_FLOAT_RE = re.compile(r"[+-]?(?:\d+\.\d*|\.\d+)(?:[eE][+-]?\d+)?|[+-]?\d+[eE][+-]?\d+")
+
+
+def is_missing(value: Any) -> bool:
+    """None, NaN (float, numpy or Decimal) and pandas ``NA`` / ``NaT``."""
+    if value is None or type(value).__name__ in ("NAType", "NaTType"):
+        return True
+    return isinstance(value, numbers.Number) and value != value
+
+
+def is_numeric(value: Any) -> bool:
+    return isinstance(value, numbers.Number) and not isinstance(value, bool)
+
+
+def parse_number(text: str) -> Union[str, int, float]:
+    """Convert numeric-looking CSV text to int/float; leave everything else.
+
+    Integers with leading zeros (IDs, ZIP codes) and thousands separators are
+    kept as text so no information is lost.
+    """
+    stripped = text.strip()
+    if _INT_RE.fullmatch(stripped):
+        return int(stripped)
+    if _FLOAT_RE.fullmatch(stripped):
+        return float(stripped)
+    return text
+
+
+def build_table(
+    keys: Sequence[Any],
+    rows: Sequence[Sequence[Any]],
+    *,
+    columns: Optional[Sequence[Any]] = None,
+    headers: Headers = None,
+    formats: Formats = None,
+    align: Optional[Sequence[str]] = None,
+    missing: str = "",
+    caption: str = "",
+) -> "Table":
+    """Shared core: select columns, format values and build a :class:`Table`."""
+    from .elements import Table
+
+    if columns is not None:
+        unknown = [c for c in columns if c not in keys]
+        if unknown:
+            raise ValueError(f"Unknown column(s): {', '.join(map(repr, unknown))}")
+        indices = [list(keys).index(c) for c in columns]
+        keys = list(columns)
+        rows = [[row[i] for i in indices] for row in rows]
+    keys = list(keys)
+
+    if headers is None:
+        labels: list = [str(k) for k in keys]
+    elif isinstance(headers, Mapping):
+        _check_keys(headers, keys, "headers")
+        labels = [headers.get(k, str(k)) for k in keys]
+    else:
+        labels = list(headers)
+        if len(labels) != len(keys):
+            raise ValueError(f"headers has {len(labels)} entries, expected {len(keys)}")
+
+    if formats is None or isinstance(formats, str) or callable(formats):
+        default_format, per_column = formats, {}
+    else:
+        _check_keys(formats, keys, "formats")
+        default_format, per_column = None, dict(formats)
+
+    columns_values = list(zip(*rows)) if rows else [() for _ in keys]
+    if align is None:
+        align = ["right" if _numeric_column(values) else "left" for values in columns_values]
+
+    cells = [
+        [
+            _format(value, per_column.get(key), default_format, missing)
+            for key, value in zip(keys, row)
+        ]
+        for row in rows
+    ]
+    return Table(labels, cells, caption=caption, align=align)
+
+
+def from_records(
+    records: Iterable[Mapping[Any, Any]],
+    columns: Optional[Sequence[Any]] = None,
+    **options: Any,
+) -> "Table":
+    records = list(records)
+    for i, record in enumerate(records):
+        if not isinstance(record, Mapping):
+            raise TypeError(f"Record {i} is a {type(record).__name__}, expected a mapping")
+    keys: list = []
+    for record in records:  # union of keys in first-seen order
+        keys.extend(k for k in record if k not in keys)
+    if columns is not None and records:
+        # Unlike keys absent from some records (filled with ``missing``), a
+        # column absent from every record is almost certainly a typo.
+        unknown = [c for c in columns if c not in keys]
+        if unknown:
+            raise ValueError(f"Unknown column(s): {', '.join(map(repr, unknown))}")
+    elif columns is not None:
+        keys = list(columns)
+    rows = [[record.get(k) for k in keys] for record in records]
+    return build_table(keys, rows, columns=columns, **options)
+
+
+def from_csv(
+    source: Union[str, Path, IO[str]],
+    columns: Optional[Sequence[str]] = None,
+    *,
+    delimiter: str = ",",
+    encoding: str = "utf-8",
+    parse_numbers: bool = True,
+    **options: Any,
+) -> "Table":
+    if hasattr(source, "read"):
+        text = source.read()  # type: ignore[union-attr]
+    else:
+        text = Path(source).read_text(encoding=encoding)
+    # utf-8-sig behaviour for any encoding: drop a leading byte-order mark.
+    lines = list(csv.reader(io.StringIO(text.lstrip("")), delimiter=delimiter))
+    lines = [line for line in lines if line]  # skip blank lines
+    if not lines:
+        raise ValueError("CSV input is empty; expected a header row")
+    keys, body = lines[0], lines[1:]
+    rows: list[list] = []
+    for n, line in enumerate(body, start=2):
+        if len(line) > len(keys):
+            raise ValueError(f"CSV line {n} has {len(line)} fields, expected {len(keys)}")
+        values: list = [None if v == "" else v for v in line]
+        rows.append(values + [None] * (len(keys) - len(values)))
+    if parse_numbers:
+        for i in range(len(keys)):
+            # All or nothing per column, so a ZIP-code column holding both
+            # "00501" and "90210" stays text instead of mixing types.
+            parsed = [parse_number(row[i]) if row[i] is not None else None for row in rows]
+            if all(p is None or not isinstance(p, str) for p in parsed):
+                for row, value in zip(rows, parsed):
+                    row[i] = value
+    return build_table(keys, rows, columns=columns, **options)
+
+
+def from_dataframe(
+    df: Any,
+    columns: Optional[Sequence[Any]] = None,
+    *,
+    index: bool = False,
+    **options: Any,
+) -> "Table":
+    if not (hasattr(df, "columns") and hasattr(df, "itertuples")):
+        raise TypeError(f"Expected a pandas-like DataFrame, got {type(df).__name__}")
+    keys = list(df.columns)
+    rows = [list(row) for row in df.itertuples(index=index, name=None)]
+    if index:
+        index_key = df.index.name if df.index.name is not None else ""
+        keys = [index_key] + keys
+        if columns is not None and index_key not in columns:
+            columns = [index_key] + list(columns)
+    return build_table(keys, rows, columns=columns, **options)
+
+
+def _check_keys(mapping: Mapping, keys: Sequence[Any], what: str) -> None:
+    unknown = [k for k in mapping if k not in keys]
+    if unknown:
+        raise ValueError(f"{what} names unknown column(s): {', '.join(map(repr, unknown))}")
+
+
+def _numeric_column(values: Sequence[Any]) -> bool:
+    present = [v for v in values if not is_missing(v)]
+    return bool(present) and all(is_numeric(v) for v in present)
+
+
+def _format(value: Any, column_format: Optional[CellFormat], default_format: Optional[CellFormat], missing: str) -> TextLike:
+    if is_missing(value):
+        return missing
+    if isinstance(value, (list, tuple)):
+        return value  # already TextLike (mixed str/Inline content)
+    fmt = column_format
+    if fmt is None and is_numeric(value):
+        fmt = default_format  # a single format applies to numbers only
+    if fmt is None:
+        return value if isinstance(value, (str, Inline)) else str(value)
+    if callable(fmt):
+        return fmt(value)
+    return fmt.format(value)

{reportsmith-0.2.0 → reportsmith-0.3.0}/reportsmith/elements.py

@@ -8,10 +8,15 @@ with the same methods.
 
 from __future__ import annotations
 
-from typing import Optional, Sequence
+from collections.abc import Mapping
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Any, Iterable, Optional, Sequence, Union
 
 from .inline import InlineContent, TextLike, normalize
 
+if TYPE_CHECKING:
+    from .data import Formats, Headers
+
 
 class Element:
     """Base class for all block elements."""
@@ -79,6 +84,85 @@ class Table(Element):
                     raise ValueError(f"Invalid alignment: {a!r}")
         self.align = list(align) if align is not None else ["left"] * width
 
+    # -- construction from data ------------------------------------------
+    # Shared options: ``columns`` selects and orders columns; ``headers``
+    # relabels them (a list, or a column -> label mapping); ``formats`` is a
+    # format string / callable applied to every numeric cell, or a
+    # column -> format mapping applied to every value in that column;
+    # ``missing`` replaces None/NaN/NA; ``align=None`` right-aligns numeric
+    # columns and left-aligns the rest.
+
+    @classmethod
+    def from_records(
+        cls,
+        records: Iterable[Mapping[Any, Any]],
+        columns: Optional[Sequence[Any]] = None,
+        *,
+        headers: Headers = None,
+        formats: Formats = None,
+        align: Optional[Sequence[str]] = None,
+        missing: str = "",
+        caption: str = "",
+    ) -> "Table":
+        """Build a table from a sequence of dicts (keys become headers)."""
+        from .data import from_records
+
+        return from_records(
+            records, columns, headers=headers, formats=formats,
+            align=align, missing=missing, caption=caption,
+        )
+
+    @classmethod
+    def from_csv(
+        cls,
+        source: Union[str, Path, IO[str]],
+        columns: Optional[Sequence[str]] = None,
+        *,
+        delimiter: str = ",",
+        encoding: str = "utf-8",
+        parse_numbers: bool = True,
+        headers: Headers = None,
+        formats: Formats = None,
+        align: Optional[Sequence[str]] = None,
+        missing: str = "",
+        caption: str = "",
+    ) -> "Table":
+        """Build a table from a CSV file path or open text file.
+
+        The first row is the header. With ``parse_numbers=True`` numeric
+        fields become numbers (so formats and auto-alignment apply);
+        integers with leading zeros stay text.
+        """
+        from .data import from_csv
+
+        return from_csv(
+            source, columns, delimiter=delimiter, encoding=encoding,
+            parse_numbers=parse_numbers, headers=headers, formats=formats,
+            align=align, missing=missing, caption=caption,
+        )
+
+    @classmethod
+    def from_dataframe(
+        cls,
+        df: Any,
+        columns: Optional[Sequence[Any]] = None,
+        *,
+        index: bool = False,
+        headers: Headers = None,
+        formats: Formats = None,
+        align: Optional[Sequence[str]] = None,
+        missing: str = "",
+        caption: str = "",
+    ) -> "Table":
+        """Build a table from a pandas DataFrame (pandas is not required by
+        reportsmith itself). ``index=True`` adds the index as the first column."""
+        from .data import from_dataframe
+
+        return from_dataframe(
+            df, columns, index=index, headers=headers, formats=formats,
+            align=align, missing=missing, caption=caption,
+        )
+
 
 class Image(Element):
     def __init__(self, src: str, alt: str = "", title: str = ""):
@@ -108,6 +192,21 @@ class Raw(Element):
         self.format = format
 
 
+class TableOfContents(Element):
+    """A table of contents listing the report's sections and headings.
+
+    Always covers the whole report, wherever it is placed. ``depth`` limits
+    how many heading levels are listed: 1 lists only top-level sections, 2
+    adds their subsections, and so on (up to 5).
+    """
+
+    def __init__(self, title: str = "Contents", depth: int = 3):
+        if not 1 <= depth <= 5:
+            raise ValueError(f"TOC depth must be 1-5, got {depth}")
+        self.title = title
+        self.depth = depth
+
+
 class Container(Element):
     """Mixin providing the fluent builder API shared by Report and Section."""
 
@@ -161,6 +260,33 @@ class Container(Element):
         self.children.append(Table(headers, rows, caption, align))
         return self
 
+    def table_from_records(
+        self,
+        records: Iterable[Mapping[Any, Any]],
+        columns: Optional[Sequence[Any]] = None,
+        **options: Any,
+    ) -> "Container":
+        """Add a table built from dicts; see :meth:`Table.from_records`."""
+        self.children.append(Table.from_records(records, columns, **options))
+        return self
+
+    def table_from_csv(
+        self,
+        source: Union[str, Path, IO[str]],
+        columns: Optional[Sequence[str]] = None,
+        **options: Any,
+    ) -> "Container":
+        """Add a table read from CSV; see :meth:`Table.from_csv`."""
+        self.children.append(Table.from_csv(source, columns, **options))
+        return self
+
+    def table_from_dataframe(
+        self, df: Any, columns: Optional[Sequence[Any]] = None, **options: Any
+    ) -> "Container":
+        """Add a table built from a DataFrame; see :meth:`Table.from_dataframe`."""
+        self.children.append(Table.from_dataframe(df, columns, **options))
+        return self
+
     def image(self, src: str, alt: str = "", title: str = "") -> "Container":
         self.children.append(Image(src, alt, title))
         return self
@@ -173,6 +299,11 @@ class Container(Element):
         self.children.append(Raw(content, format))
         return self
 
+    def toc(self, title: str = "Contents", depth: int = 3) -> "Container":
+        """Add a table of contents for the whole report."""
+        self.children.append(TableOfContents(title, depth))
+        return self
+
 
 class Section(Container):
     """A titled group of elements; nests to any depth.

{reportsmith-0.2.0 → reportsmith-0.3.0}/reportsmith/renderers/html.py

@@ -17,8 +17,10 @@ from ..elements import (
     Raw,
     Section,
     Table,
+    TableOfContents,
 )
 from ..inline import Inline, InlineContent
+from ..toc import TocEntry, build_tree, collect_entries, find_tocs, heading_anchors
 
 if TYPE_CHECKING:
     from ..report import Report
@@ -68,6 +70,12 @@ pre code { background: none; padding: 0; }
 blockquote { border-left: 4px solid var(--border); color: var(--muted); margin: 1em 0; padding: 0.1em 1em; }
 img { max-width: 100%; }
 hr { border: none; border-top: 1px solid var(--border); margin: 2em 0; }
+nav.toc { border: 1px solid var(--border); border-radius: 8px; padding: 0.8em 1.2em; margin: 1.5em 0; }
+nav.toc .toc-title { font-weight: 600; margin-bottom: 0.3em; }
+nav.toc ul { list-style: none; margin: 0; padding-left: 1.2em; }
+nav.toc > ul { padding-left: 0; }
+nav.toc a { text-decoration: none; }
+nav.toc a:hover { text-decoration: underline; }
 """
 
 
@@ -99,6 +107,10 @@ class HtmlRenderer:
         )
 
     def _body(self, report: "Report") -> str:
+        self._report = report
+        # Headings only get ids when there is a TOC to link to them, so
+        # output for reports without one is unchanged.
+        self._anchors = heading_anchors(report) if any(find_tocs(report)) else {}
         parts = [f"<h1>{escape(report.title)}</h1>\n"]
         meta = []
         if report.subtitle:
@@ -118,11 +130,11 @@ class HtmlRenderer:
     def _render_element(self, el: Element) -> str:
         if isinstance(el, Section):
             level = el._level
-            out = [f"<h{level}>{self._inline(el.title_parts)}</h{level}>\n"]
+            out = [f"<h{level}{self._id(el)}>{self._inline(el.title_parts)}</h{level}>\n"]
             out.extend(self._render_element(child) for child in el.children)
             return "".join(out)
         if isinstance(el, Heading):
-            return f"<h{el.level}>{self._inline(el.parts)}</h{el.level}>\n"
+            return f"<h{el.level}{self._id(el)}>{self._inline(el.parts)}</h{el.level}>\n"
         if isinstance(el, Paragraph):
             return f"<p>{self._inline(el.parts)}</p>\n"
         if isinstance(el, Quote):
@@ -144,8 +156,42 @@ class HtmlRenderer:
             return "<hr>\n"
         if isinstance(el, Raw):
             return el.content + "\n" if el.format in ("html", "both") else ""
+        if isinstance(el, TableOfContents):
+            return self._toc(el)
         raise TypeError(f"Cannot render element of type {type(el).__name__}")
 
+    def _id(self, el: Element) -> str:
+        anchor = self._anchors.get(id(el))
+        return f' id="{escape(anchor, quote=True)}"' if anchor else ""
+
+    def _toc(self, el: TableOfContents) -> str:
+        label = escape(el.title or "Contents", quote=True)
+        out = [f'<nav class="toc" aria-label="{label}">\n']
+        if el.title:
+            out.append(f'<div class="toc-title">{escape(el.title)}</div>\n')
+
+        def walk(entries: list[TocEntry]) -> None:
+            out.append("<ul>\n")
+            for entry in entries:
+                anchor = escape(self._anchors[id(entry.element)], quote=True)
+                # Links can't nest inside the entry's own <a>; keep their text.
+                parts = [
+                    p.text if isinstance(p, Inline) and p.style == "link" else p
+                    for p in entry.parts
+                ]
+                out.append(f'<li><a href="#{anchor}">{self._inline(parts)}</a>')
+                if entry.children:
+                    out.append("\n")
+                    walk(entry.children)
+                out.append("</li>\n")
+            out.append("</ul>\n")
+
+        entries = build_tree(collect_entries(self._report, el.depth))
+        if entries:
+            walk(entries)
+        out.append("</nav>\n")
+        return "".join(out)
+
     def _list(self, el: ListElement) -> str:
         tag = "ol" if el.ordered else "ul"
         out = [f"<{tag}>\n"]

{reportsmith-0.2.0 → reportsmith-0.3.0}/reportsmith/renderers/latex.py

@@ -16,6 +16,7 @@ from ..elements import (
     Raw,
     Section,
     Table,
+    TableOfContents,
 )
 from ..inline import Inline, InlineContent
 
@@ -171,6 +172,13 @@ class LatexRenderer:
             return "\\par\\noindent\\rule{\\linewidth}{0.4pt}\\par\n\n"
         if isinstance(el, Raw):
             return el.content + "\n\n" if el.format == "latex" else ""
+        if isinstance(el, TableOfContents):
+            # Grouped so the renamed heading stays local to this TOC. Our
+            # depth 1 (top-level sections) is LaTeX's tocdepth 1 (\section).
+            return (
+                f"{{\\renewcommand{{\\contentsname}}{{{escape_latex(el.title)}}}"
+                f"\\setcounter{{tocdepth}}{{{el.depth}}}\\tableofcontents}}\n\n"
+            )
         raise TypeError(f"Cannot render element of type {type(el).__name__}")
 
     def _code(self, el: CodeBlock) -> str:

{reportsmith-0.2.0 → reportsmith-0.3.0}/reportsmith/renderers/markdown.py

@@ -16,8 +16,10 @@ from ..elements import (
     Raw,
     Section,
     Table,
+    TableOfContents,
 )
 from ..inline import Inline, InlineContent
+from ..toc import TocEntry, build_tree, collect_entries, heading_anchors, plain_text
 
 if TYPE_CHECKING:
     from ..report import Report
@@ -29,6 +31,8 @@ class MarkdownRenderer:
     """Renders a Report to GitHub-flavored Markdown."""
 
     def render(self, report: "Report") -> str:
+        self._report = report
+        self._anchors = heading_anchors(report)
         blocks: list[str] = [f"# {report.title}"]
         meta = self._metadata_lines(report)
         if meta:
@@ -79,8 +83,27 @@ class MarkdownRenderer:
             return ["---"]
         if isinstance(el, Raw):
             return [el.content] if el.format in ("markdown", "both") else []
+        if isinstance(el, TableOfContents):
+            return self._toc(el)
         raise TypeError(f"Cannot render element of type {type(el).__name__}")
 
+    def _toc(self, el: TableOfContents) -> list[str]:
+        blocks = [f"**{el.title}**"] if el.title else []
+        lines: list[str] = []
+
+        def walk(entries: list[TocEntry], indent: int) -> None:
+            for entry in entries:
+                # Plain text: inline markup can't nest inside link text.
+                text = plain_text(entry.parts).replace("[", r"\[").replace("]", r"\]")
+                anchor = self._anchors[id(entry.element)]
+                lines.append(f"{'  ' * indent}- [{text}](#{anchor})")
+                walk(entry.children, indent + 1)
+
+        walk(build_tree(collect_entries(self._report, el.depth)), 0)
+        if lines:
+            blocks.append("\n".join(lines))
+        return blocks
+
     def _list_lines(self, el: ListElement, indent: int) -> list[str]:
         lines: list[str] = []
         pad = "  " * indent