mddoco 2.0.0__tar.gz → 2.0.3__tar.gz

{mddoco-2.0.0/src/mddoco.egg-info → mddoco-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mddoco
-Version: 2.0.0
+Version: 2.0.3
 Summary: Markdown to HTML/PDF document converter
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -10,6 +10,10 @@ Requires-Dist: markdown>=3.5
 Requires-Dist: jinja2>=3.1
 Requires-Dist: playwright>=1.40
 Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
 Dynamic: license-file
 
 # mddoco
@@ -20,17 +24,23 @@ A CLI tool that converts markdown files to a single HTML (or future PDF) documen
 
 ```bash
 pip install mddoco
-playwright install chromium
 ```
 
 Or for development:
 
 ```bash
 pip install -e .
-playwright install chromium
 ```
 
-> Playwright (Chromium) is required for PDF output only. HTML output works without it.
+> **Playwright (Chromium) is required for PDF output only.** HTML output works without it.
+> The `playwright` Python package is installed automatically, but the Chromium
+> browser it drives is not. The first time you render a PDF, mddoco downloads
+> Chromium for you (~150 MB, one time). To do it ahead of time, or if the
+> automatic download fails, run it yourself:
+>
+> ```bash
+> playwright install chromium
+> ```
 
 ## Usage
 
@@ -79,25 +89,43 @@ All matched markdown files are combined into a single HTML document in the outpu
 
 Files ending in `.md.j2` are Jinja2 templates that produce Markdown. They are sorted alongside regular `.md` files (numeric prefixes such as `01_`, `02_` determine order) and converted through the same pipeline.
 
-### JSON context variables
+### Context variables (JSON and CSV)
 
-Place `*.json` files in the same input directory. Each file's stem becomes a top-level variable in the Jinja2 context — `report.json` is available as `report`, `config.json` as `config`, and so on.
+Place `*.json` or `*.csv` files in the same input directory. Each file's stem becomes a top-level variable in the Jinja2 context — `report.json` is available as `report`, `people.csv` as `people`, and so on. If both `data.json` and `data.csv` exist, the tool will exit with an error.
 
 ```
 docs/
   01_intro.md
   02_summary.md.j2    ← Jinja2 template
-  report.json         ← available as {{ report }} inside *.md.j2 files
+  report.json         ← available as {{ report }}
+  people.csv          ← available as {{ people }}
 ```
 
-Example template (`02_summary.md.j2`):
+**JSON** files are loaded as-is; the variable holds whatever structure the JSON contains.
+
+**CSV** files are loaded as a list of row dicts, one dict per row:
 
 ```markdown
-# Summary for {{ report.project }}
+{% for person in people %}
+- {{ person.name }} ({{ person.role }})
+{% endfor %}
+```
 
-Generated by: {{ report.author }}
+Cell values containing `;` are automatically split into a list:
+
+```csv
+name,skills
+Alice,python;flask;sql
+Bob,java
 ```
 
+```markdown
+{{ people[0].skills }}   {# → ["python", "flask", "sql"] #}
+{{ people[1].skills }}   {# → "java" (plain string — no ;) #}
+```
+
+Quoting a field in the CSV prevents `;` splitting — `"python;flask"` remains a single string.
+
 ### Excluding files
 
 Files whose name starts with `_` are excluded from scanning. Use this for Jinja2 macro files that should be imported but not rendered as documents:
@@ -109,6 +137,24 @@ docs/
   02_report.md.j2
 ```
 
+### Using macros
+
+Use `{% import %}` or `{% from ... import %}` to make macros from another file callable — **not** `{% include %}`. `{% include %}` injects rendered output only; macros defined in an included file are not visible to the calling template and will raise an `undefined` error.
+
+```jinja
+{# correct — macro is callable after this #}
+{% import "_macros.j2" as macros %}
+{{ macros.val(item) }}
+
+{# also correct #}
+{% from "_macros.j2" import val %}
+{{ val(item) }}
+
+{# wrong — val will be undefined #}
+{% include "_macros.j2" %}
+{{ val(item) }}
+```
+
 ## Themes
 
 Themes are self-contained Jinja2 HTML files with embedded CSS. Pass a theme name with `--theme NAME`.

{mddoco-2.0.0 → mddoco-2.0.3}/README.md

@@ -6,17 +6,23 @@ A CLI tool that converts markdown files to a single HTML (or future PDF) documen
 
 ```bash
 pip install mddoco
-playwright install chromium
 ```
 
 Or for development:
 
 ```bash
 pip install -e .
-playwright install chromium
 ```
 
-> Playwright (Chromium) is required for PDF output only. HTML output works without it.
+> **Playwright (Chromium) is required for PDF output only.** HTML output works without it.
+> The `playwright` Python package is installed automatically, but the Chromium
+> browser it drives is not. The first time you render a PDF, mddoco downloads
+> Chromium for you (~150 MB, one time). To do it ahead of time, or if the
+> automatic download fails, run it yourself:
+>
+> ```bash
+> playwright install chromium
+> ```
 
 ## Usage
 
@@ -65,25 +71,43 @@ All matched markdown files are combined into a single HTML document in the outpu
 
 Files ending in `.md.j2` are Jinja2 templates that produce Markdown. They are sorted alongside regular `.md` files (numeric prefixes such as `01_`, `02_` determine order) and converted through the same pipeline.
 
-### JSON context variables
+### Context variables (JSON and CSV)
 
-Place `*.json` files in the same input directory. Each file's stem becomes a top-level variable in the Jinja2 context — `report.json` is available as `report`, `config.json` as `config`, and so on.
+Place `*.json` or `*.csv` files in the same input directory. Each file's stem becomes a top-level variable in the Jinja2 context — `report.json` is available as `report`, `people.csv` as `people`, and so on. If both `data.json` and `data.csv` exist, the tool will exit with an error.
 
 ```
 docs/
   01_intro.md
   02_summary.md.j2    ← Jinja2 template
-  report.json         ← available as {{ report }} inside *.md.j2 files
+  report.json         ← available as {{ report }}
+  people.csv          ← available as {{ people }}
 ```
 
-Example template (`02_summary.md.j2`):
+**JSON** files are loaded as-is; the variable holds whatever structure the JSON contains.
+
+**CSV** files are loaded as a list of row dicts, one dict per row:
 
 ```markdown
-# Summary for {{ report.project }}
+{% for person in people %}
+- {{ person.name }} ({{ person.role }})
+{% endfor %}
+```
 
-Generated by: {{ report.author }}
+Cell values containing `;` are automatically split into a list:
+
+```csv
+name,skills
+Alice,python;flask;sql
+Bob,java
 ```
 
+```markdown
+{{ people[0].skills }}   {# → ["python", "flask", "sql"] #}
+{{ people[1].skills }}   {# → "java" (plain string — no ;) #}
+```
+
+Quoting a field in the CSV prevents `;` splitting — `"python;flask"` remains a single string.
+
 ### Excluding files
 
 Files whose name starts with `_` are excluded from scanning. Use this for Jinja2 macro files that should be imported but not rendered as documents:
@@ -95,6 +119,24 @@ docs/
   02_report.md.j2
 ```
 
+### Using macros
+
+Use `{% import %}` or `{% from ... import %}` to make macros from another file callable — **not** `{% include %}`. `{% include %}` injects rendered output only; macros defined in an included file are not visible to the calling template and will raise an `undefined` error.
+
+```jinja
+{# correct — macro is callable after this #}
+{% import "_macros.j2" as macros %}
+{{ macros.val(item) }}
+
+{# also correct #}
+{% from "_macros.j2" import val %}
+{{ val(item) }}
+
+{# wrong — val will be undefined #}
+{% include "_macros.j2" %}
+{{ val(item) }}
+```
+
 ## Themes
 
 Themes are self-contained Jinja2 HTML files with embedded CSS. Pass a theme name with `--theme NAME`.

{mddoco-2.0.0 → mddoco-2.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mddoco"
-version = "2.0.0"
+version = "2.0.3"
 description = "Markdown to HTML/PDF document converter"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -16,6 +16,13 @@ dependencies = [
     "matplotlib>=3.7",
 ]
 
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "black>=24.0",
+    "ruff>=0.16,<0.17",
+]
+
 [project.scripts]
 mddoco = "mddoco.cli:main"
 
@@ -25,9 +32,16 @@ where = ["src"]
 [tool.setuptools.package-data]
 mddoco = ["themes/*.html"]
 
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+
 [tool.ruff]
 src = ["src"]
 line-length = 88
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mddoco-2.0.3/src/mddoco/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.3"

{mddoco-2.0.0 → mddoco-2.0.3}/src/mddoco/cli.py

@@ -5,7 +5,7 @@ import click
 
 from mddoco.converter import convert_files
 from mddoco.pdf import html_to_pdf
-from mddoco.preprocessor import load_json_context
+from mddoco.preprocessor import load_context
 from mddoco.renderer import render_html
 from mddoco.scanner import find_markdown_files
 from mddoco.toc import combine_toc
@@ -15,31 +15,40 @@ from mddoco.writer import write_output
 @click.command()
 @click.argument("input_path", type=click.Path(exists=True, path_type=Path))
 @click.option(
-    "--output", "-o", "output_path",
-    default=".", show_default=True,
+    "--output",
+    "-o",
+    "output_path",
+    default=".",
+    show_default=True,
     type=click.Path(path_type=Path),
     help="Output directory, or explicit output file path.",
 )
 @click.option(
-    "--format", "-f", "fmt",
-    default="html", show_default=True,
+    "--format",
+    "-f",
+    "fmt",
+    default="html",
+    show_default=True,
     type=click.Choice(["html", "pdf"], case_sensitive=False),
     help="Output format.",
 )
 @click.option("--title", "-t", default=None, help="Document title.")
 @click.option(
     "--theme",
-    default="default", show_default=True,
+    default="default",
+    show_default=True,
     help="Theme name to use for rendering.",
 )
 @click.option(
     "--toc/--no-toc",
-    default=False, show_default=True,
+    default=False,
+    show_default=True,
     help="Generate a table of contents.",
 )
 @click.option(
     "--toc-depth",
-    default=3, show_default=True,
+    default=3,
+    show_default=True,
     type=click.IntRange(1, 6),
     help="Maximum heading depth included in the TOC.",
 )
@@ -63,7 +72,7 @@ def main(
     click.echo(f"Found {len(md_files)} markdown file(s).")
 
     try:
-        context = load_json_context(input_path)
+        context = load_context(input_path)
         raw = convert_files(md_files, toc=toc, toc_depth=toc_depth, context=context)
     except Exception as exc:
         raise click.ClickException(str(exc)) from exc

{mddoco-2.0.0 → mddoco-2.0.3}/src/mddoco/graph.py

@@ -6,84 +6,105 @@ import re
 from html import unescape
 
 import matplotlib
-matplotlib.use('Agg')  # non-interactive backend — must be set before importing pyplot
+
+matplotlib.use("Agg")  # non-interactive backend — must be set before importing pyplot
 import matplotlib.pyplot as plt
 
 log = logging.getLogger(__name__)
 
-_JSON_TO_PY = re.compile(r'\b(true|false|null)\b')
-_JSON_TO_PY_MAP = {'true': 'True', 'false': 'False', 'null': 'None'}
+_JSON_TO_PY = re.compile(r"\b(true|false|null)\b")
+_JSON_TO_PY_MAP = {"true": "True", "false": "False", "null": "None"}
 
 _DEFAULT_COLOURS = [
-    '#2d6cbe', '#e74c3c', '#27ae60', '#e67e22',
-    '#8e44ad', '#16a085', '#2c3e50', '#d35400',
+    "#2d6cbe",
+    "#e74c3c",
+    "#27ae60",
+    "#e67e22",
+    "#8e44ad",
+    "#16a085",
+    "#2c3e50",
+    "#d35400",
 ]
 
 
 def graph_it(data, output=None):
     dpi = 100
-    width_px = data.get('width_px', 640)
-    height_px = data.get('height_px', 480)
+    width_px = data.get("width_px", 640)
+    height_px = data.get("height_px", 480)
     fig, ax = plt.subplots(figsize=(width_px / dpi, height_px / dpi), dpi=dpi)
 
-    orientation = data.get('orientation', 'vertical').lower()
-    if orientation not in ('horizontal', 'vertical'):
+    orientation = data.get("orientation", "vertical").lower()
+    if orientation not in ("horizontal", "vertical"):
         raise ValueError(
             f"Invalid orientation '{orientation}' — must be 'horizontal' or 'vertical'"
         )
-    horizontal = orientation == 'horizontal'
+    horizontal = orientation == "horizontal"
 
-    x = data['data']['x']
+    x = data["data"]["x"]
 
     # Auto-generate series from data keys (everything except 'x') if not provided
-    series_list = data.get('series') or [
-        {'label': k} for k in data['data'] if k != 'x'
-    ]
+    series_list = data.get("series") or [{"label": k} for k in data["data"] if k != "x"]
 
     for i, series in enumerate(series_list):
-        label = series['label']
-        values = data['data'][label]
-        series_type = series.get('type', 'line')
-        colour = series.get('colour', _DEFAULT_COLOURS[i % len(_DEFAULT_COLOURS)])
+        label = series["label"]
+        values = data["data"][label]
+        series_type = series.get("type", "line")
+        colour = series.get("colour", _DEFAULT_COLOURS[i % len(_DEFAULT_COLOURS)])
 
-        if series_type == 'bar':
+        if series_type == "bar":
             colour_val = colour if isinstance(colour, list) else [colour] * len(values)
             if horizontal:
                 ax.barh(x, values, color=colour_val, label=label)
             else:
                 ax.bar(x, values, color=colour_val, label=label)
-        elif series_type in ('line', 'line2'):
-            marker = 'o' if series.get('marker', False) else 'None'
-            linestyle = ':' if series_type == 'line2' else '-'
+        elif series_type in ("line", "line2"):
+            marker = "o" if series.get("marker", False) else "None"
+            linestyle = ":" if series_type == "line2" else "-"
             if horizontal:
-                ax.plot(values, x, color=colour, marker=marker, linewidth=2, linestyle=linestyle, label=label)
+                ax.plot(
+                    values,
+                    x,
+                    color=colour,
+                    marker=marker,
+                    linewidth=2,
+                    linestyle=linestyle,
+                    label=label,
+                )
             else:
-                ax.plot(x, values, color=colour, marker=marker, linewidth=2, linestyle=linestyle, label=label)
-
-    if 'min' in data or 'max' in data:
-        lo = data.get('min', None)
-        hi = data.get('max', None)
+                ax.plot(
+                    x,
+                    values,
+                    color=colour,
+                    marker=marker,
+                    linewidth=2,
+                    linestyle=linestyle,
+                    label=label,
+                )
+
+    if "min" in data or "max" in data:
+        lo = data.get("min", None)
+        hi = data.get("max", None)
         if horizontal:
             ax.set_xlim(lo, hi)
         else:
             ax.set_ylim(lo, hi)
 
-    title = data.get('title', '')
+    title = data.get("title", "")
     if title:
         ax.set_title(title)
 
-    if data.get('show_legend', True):
-        ax.legend(loc='upper left')
+    if data.get("show_legend", True):
+        ax.legend(loc="upper left")
 
-    ax.spines['top'].set_visible(False)
-    ax.spines['right'].set_visible(False)
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
 
     if output:
-        plt.savefig(output, format="svg", bbox_inches='tight')
+        plt.savefig(output, format="svg", bbox_inches="tight")
         plt.close(fig)
     else:
         buf = io.StringIO()
-        plt.savefig(buf, format="svg", bbox_inches='tight')
+        plt.savefig(buf, format="svg", bbox_inches="tight")
         plt.close(fig)
         return buf.getvalue()
 
@@ -93,7 +114,7 @@ _GRAPH_BLOCK = re.compile(
     re.DOTALL,
 )
 
-_SVG_HEADER = re.compile(r'^.*?(?=<svg)', re.DOTALL)
+_SVG_HEADER = re.compile(r"^.*?(?=<svg)", re.DOTALL)
 
 
 def _parse_source(source: str) -> dict:
@@ -113,7 +134,7 @@ def _render_graph(source: str) -> str:
     """Parse source, render via graph_it, and return an inline SVG element."""
     data = _parse_source(source)
     svg = graph_it(data)
-    svg = _SVG_HEADER.sub('', svg)  # strip XML declaration and DOCTYPE
+    svg = _SVG_HEADER.sub("", svg)  # strip XML declaration and DOCTYPE
     return f'<div class="graph">{svg}</div>'
 
 

mddoco-2.0.3/src/mddoco/pdf.py

@@ -0,0 +1,78 @@
+import logging
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+_INSTALL_HINT = (
+    "Chromium is required for PDF output and could not be installed "
+    "automatically. Run: playwright install chromium"
+)
+
+
+def html_to_pdf(html_content: str, dest: Path) -> None:
+    """Render an HTML string to a PDF file using a headless Chromium browser.
+
+    Navigates via a temporary file:// URL so that external resources (CDN
+    scripts, Mermaid.js, etc.) load correctly before the page is printed.
+
+    The Chromium binary that Playwright drives is not shipped with the Python
+    package. The first time a PDF is rendered on a fresh machine it is
+    downloaded automatically; if that download fails the user is told how to
+    install it by hand.
+    """
+    try:
+        from playwright.sync_api import Error as PlaywrightError
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        raise RuntimeError(
+            "Playwright is required for PDF output. "
+            "Run: pip install playwright && playwright install chromium"
+        )
+
+    with tempfile.NamedTemporaryFile(
+        suffix=".html", delete=False, mode="w", encoding="utf-8"
+    ) as f:
+        f.write(html_content)
+        tmp_path = Path(f.name)
+
+    try:
+        try:
+            _render(sync_playwright, tmp_path, dest)
+        except PlaywrightError as exc:
+            if "Executable doesn't exist" not in str(exc):
+                raise
+            _install_chromium()
+            _render(sync_playwright, tmp_path, dest)
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def _render(sync_playwright, source: Path, dest: Path) -> None:
+    """Drive headless Chromium to print ``source`` to ``dest`` as A4 PDF."""
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        page = browser.new_page()
+        page.goto(source.as_uri(), wait_until="networkidle")
+        # If Paged.js is present, wait for it to finish paginating before
+        # capturing — networkidle fires before its JS layout pass completes.
+        page.wait_for_function(
+            "typeof window.PagedPolyfill === 'undefined'"
+            " || !!document.querySelector('.pagedjs_pages')"
+        )
+        page.pdf(path=str(dest), format="A4", print_background=True)
+        browser.close()
+
+
+def _install_chromium() -> None:
+    """Download the Chromium binary Playwright needs, or explain how to."""
+    log.warning("Chromium not found — downloading it now (~150 MB, one time).")
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "playwright", "install", "chromium"],
+            check=True,
+        )
+    except (subprocess.CalledProcessError, OSError) as exc:
+        raise RuntimeError(_INSTALL_HINT) from exc

mddoco-2.0.3/src/mddoco/preprocessor.py

@@ -0,0 +1,132 @@
+import csv
+import json
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader
+
+
+def load_json_context(input_path: Path) -> dict:
+    """Load all *.json files from the input directory into a template context dict."""
+    directory = input_path if input_path.is_dir() else input_path.parent
+    context: dict = {}
+    for json_file in sorted(directory.glob("*.json")):
+        try:
+            data = json.loads(json_file.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in {json_file.name}: {exc}") from exc
+        context[json_file.stem] = data
+    return context
+
+
+def _parse_csv_line(line: str) -> list[tuple[str, bool]]:
+    """Parse a single CSV line into (value, was_quoted) pairs.
+
+    Handles quoted fields (including commas and escaped quotes inside them).
+    """
+    fields: list[tuple[str, bool]] = []
+    i = 0
+    n = len(line)
+
+    while True:
+        if i >= n:
+            break
+
+        if line[i] == '"':
+            i += 1
+            parts: list[str] = []
+            while i < n:
+                if line[i] == '"':
+                    if i + 1 < n and line[i + 1] == '"':
+                        parts.append('"')
+                        i += 2
+                    else:
+                        i += 1
+                        break
+                else:
+                    parts.append(line[i])
+                    i += 1
+            value = "".join(parts)
+            while i < n and line[i] != ",":
+                i += 1
+            fields.append((value, True))
+        else:
+            start = i
+            while i < n and line[i] != ",":
+                i += 1
+            fields.append((line[start:i], False))
+
+        if i < n and line[i] == ",":
+            i += 1
+            if i >= n:
+                fields.append(("", False))
+
+    return fields
+
+
+def _apply_semicolon_split(value: str, was_quoted: bool) -> str | list[str]:
+    """Return value split on ';' unless the field was originally quoted."""
+    if was_quoted or ";" not in value:
+        return value
+    return [part.strip() for part in value.split(";")]
+
+
+def load_csv_context(input_path: Path) -> dict:
+    """Load all *.csv files from the input directory into a template context dict.
+
+    Each file's stem becomes the variable name (people.csv → ``people``).
+    The value is a list of row dicts. Cell values containing ';' become lists;
+    quoted fields are never split.
+    """
+    directory = input_path if input_path.is_dir() else input_path.parent
+    context: dict = {}
+
+    for csv_file in sorted(directory.glob("*.csv")):
+        lines = csv_file.read_text(encoding="utf-8").splitlines()
+        rows: list[dict] = []
+
+        if not lines:
+            context[csv_file.stem] = rows
+            continue
+
+        header = next(csv.reader([lines[0]]))
+
+        for raw_line in lines[1:]:
+            if not raw_line.strip():
+                continue
+            fields = _parse_csv_line(raw_line)
+            row: dict = {}
+            for idx, key in enumerate(header):
+                if idx < len(fields):
+                    value, was_quoted = fields[idx]
+                else:
+                    value, was_quoted = "", False
+                row[key] = _apply_semicolon_split(value, was_quoted)
+            rows.append(row)
+
+        context[csv_file.stem] = rows
+
+    return context
+
+
+def load_context(input_path: Path) -> dict:
+    """Load JSON and CSV context files, raising ValueError on stem conflicts."""
+    json_ctx = load_json_context(input_path)
+    csv_ctx = load_csv_context(input_path)
+    conflicts = set(json_ctx) & set(csv_ctx)
+    if conflicts:
+        names = ", ".join(sorted(conflicts))
+        raise ValueError(
+            f"Context name conflict — both a .json and .csv exist for: {names}"
+        )
+    return {**json_ctx, **csv_ctx}
+
+
+def render_j2(path: Path, context: dict) -> str:
+    """Render a .md.j2 Jinja2 template and return the resulting Markdown text."""
+    env = Environment(
+        loader=FileSystemLoader(str(path.parent)),
+        autoescape=False,
+        keep_trailing_newline=True,
+    )
+    template = env.get_template(path.name)
+    return template.render(**context)

{mddoco-2.0.0 → mddoco-2.0.3/src/mddoco.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mddoco
-Version: 2.0.0
+Version: 2.0.3
 Summary: Markdown to HTML/PDF document converter
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -10,6 +10,10 @@ Requires-Dist: markdown>=3.5
 Requires-Dist: jinja2>=3.1
 Requires-Dist: playwright>=1.40
 Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
 Dynamic: license-file
 
 # mddoco
@@ -20,17 +24,23 @@ A CLI tool that converts markdown files to a single HTML (or future PDF) documen
 
 ```bash
 pip install mddoco
-playwright install chromium
 ```
 
 Or for development:
 
 ```bash
 pip install -e .
-playwright install chromium
 ```
 
-> Playwright (Chromium) is required for PDF output only. HTML output works without it.
+> **Playwright (Chromium) is required for PDF output only.** HTML output works without it.
+> The `playwright` Python package is installed automatically, but the Chromium
+> browser it drives is not. The first time you render a PDF, mddoco downloads
+> Chromium for you (~150 MB, one time). To do it ahead of time, or if the
+> automatic download fails, run it yourself:
+>
+> ```bash
+> playwright install chromium
+> ```
 
 ## Usage
 
@@ -79,25 +89,43 @@ All matched markdown files are combined into a single HTML document in the outpu
 
 Files ending in `.md.j2` are Jinja2 templates that produce Markdown. They are sorted alongside regular `.md` files (numeric prefixes such as `01_`, `02_` determine order) and converted through the same pipeline.
 
-### JSON context variables
+### Context variables (JSON and CSV)
 
-Place `*.json` files in the same input directory. Each file's stem becomes a top-level variable in the Jinja2 context — `report.json` is available as `report`, `config.json` as `config`, and so on.
+Place `*.json` or `*.csv` files in the same input directory. Each file's stem becomes a top-level variable in the Jinja2 context — `report.json` is available as `report`, `people.csv` as `people`, and so on. If both `data.json` and `data.csv` exist, the tool will exit with an error.
 
 ```
 docs/
   01_intro.md
   02_summary.md.j2    ← Jinja2 template
-  report.json         ← available as {{ report }} inside *.md.j2 files
+  report.json         ← available as {{ report }}
+  people.csv          ← available as {{ people }}
 ```
 
-Example template (`02_summary.md.j2`):
+**JSON** files are loaded as-is; the variable holds whatever structure the JSON contains.
+
+**CSV** files are loaded as a list of row dicts, one dict per row:
 
 ```markdown
-# Summary for {{ report.project }}
+{% for person in people %}
+- {{ person.name }} ({{ person.role }})
+{% endfor %}
+```
 
-Generated by: {{ report.author }}
+Cell values containing `;` are automatically split into a list:
+
+```csv
+name,skills
+Alice,python;flask;sql
+Bob,java
 ```
 
+```markdown
+{{ people[0].skills }}   {# → ["python", "flask", "sql"] #}
+{{ people[1].skills }}   {# → "java" (plain string — no ;) #}
+```
+
+Quoting a field in the CSV prevents `;` splitting — `"python;flask"` remains a single string.
+
 ### Excluding files
 
 Files whose name starts with `_` are excluded from scanning. Use this for Jinja2 macro files that should be imported but not rendered as documents:
@@ -109,6 +137,24 @@ docs/
   02_report.md.j2
 ```
 
+### Using macros
+
+Use `{% import %}` or `{% from ... import %}` to make macros from another file callable — **not** `{% include %}`. `{% include %}` injects rendered output only; macros defined in an included file are not visible to the calling template and will raise an `undefined` error.
+
+```jinja
+{# correct — macro is callable after this #}
+{% import "_macros.j2" as macros %}
+{{ macros.val(item) }}
+
+{# also correct #}
+{% from "_macros.j2" import val %}
+{{ val(item) }}
+
+{# wrong — val will be undefined #}
+{% include "_macros.j2" %}
+{{ val(item) }}
+```
+
 ## Themes
 
 Themes are self-contained Jinja2 HTML files with embedded CSS. Pass a theme name with `--theme NAME`.

{mddoco-2.0.0 → mddoco-2.0.3}/src/mddoco.egg-info/SOURCES.txt

@@ -27,4 +27,5 @@ src/mddoco/themes/default.html
 src/mddoco/themes/paged-professional.html
 src/mddoco/themes/professional-wide.html
 src/mddoco/themes/professional.html
-src/mddoco/themes/vanilla.html
+src/mddoco/themes/vanilla.html
+tests/test_preprocessor.py

{mddoco-2.0.0 → mddoco-2.0.3}/src/mddoco.egg-info/requires.txt

@@ -3,3 +3,8 @@ markdown>=3.5
 jinja2>=3.1
 playwright>=1.40
 matplotlib>=3.7
+
+[dev]
+pytest>=8.0
+black>=24.0
+ruff<0.17,>=0.16

mddoco-2.0.3/tests/test_preprocessor.py

@@ -0,0 +1,145 @@
+from pathlib import Path
+
+import pytest
+
+import mddoco
+from mddoco.preprocessor import (
+    _apply_semicolon_split,
+    _parse_csv_line,
+    load_context,
+    load_csv_context,
+)
+
+# --- version ---
+
+
+def test_version():
+    assert mddoco.__version__ == "2.0.3"
+
+
+# --- _parse_csv_line ---
+
+
+def test_parse_csv_line_simple():
+    assert _parse_csv_line("a,b,c") == [("a", False), ("b", False), ("c", False)]
+
+
+def test_parse_csv_line_quoted_field():
+    assert _parse_csv_line('a,"b;c",d') == [("a", False), ("b;c", True), ("d", False)]
+
+
+def test_parse_csv_line_quoted_field_with_comma():
+    assert _parse_csv_line('a,"b,c",d') == [("a", False), ("b,c", True), ("d", False)]
+
+
+def test_parse_csv_line_escaped_quote_inside_quoted():
+    assert _parse_csv_line('"say ""hello""",b') == [('say "hello"', True), ("b", False)]
+
+
+def test_parse_csv_line_trailing_comma():
+    assert _parse_csv_line("a,b,") == [("a", False), ("b", False), ("", False)]
+
+
+def test_parse_csv_line_single_field():
+    assert _parse_csv_line("hello") == [("hello", False)]
+
+
+# --- _apply_semicolon_split ---
+
+
+def test_split_unquoted_with_semicolon():
+    assert _apply_semicolon_split("python;flask", False) == ["python", "flask"]
+
+
+def test_split_trims_whitespace():
+    assert _apply_semicolon_split("python ; flask ; sql", False) == [
+        "python",
+        "flask",
+        "sql",
+    ]
+
+
+def test_no_split_when_quoted():
+    assert _apply_semicolon_split("python;flask", True) == "python;flask"
+
+
+def test_no_split_no_semicolon():
+    assert _apply_semicolon_split("python", False) == "python"
+
+
+def test_single_element_after_split():
+    assert _apply_semicolon_split("python;", False) == ["python", ""]
+
+
+# --- load_csv_context ---
+
+
+def test_load_csv_basic(tmp_path: Path):
+    (tmp_path / "people.csv").write_text(
+        "name,role\nAlice,Engineer\nBob,Manager\n", encoding="utf-8"
+    )
+    ctx = load_csv_context(tmp_path)
+    assert ctx == {
+        "people": [
+            {"name": "Alice", "role": "Engineer"},
+            {"name": "Bob", "role": "Manager"},
+        ]
+    }
+
+
+def test_load_csv_semicolon_becomes_list(tmp_path: Path):
+    (tmp_path / "data.csv").write_text(
+        "name,skills\nAlice,python;flask\n", encoding="utf-8"
+    )
+    ctx = load_csv_context(tmp_path)
+    assert ctx["data"][0]["skills"] == ["python", "flask"]
+
+
+def test_load_csv_quoted_semicolon_not_split(tmp_path: Path):
+    (tmp_path / "data.csv").write_text('id,label\n1,"a;b;c"\n', encoding="utf-8")
+    ctx = load_csv_context(tmp_path)
+    assert ctx["data"][0]["label"] == "a;b;c"
+
+
+def test_load_csv_multiple_files(tmp_path: Path):
+    (tmp_path / "a.csv").write_text("x\n1\n", encoding="utf-8")
+    (tmp_path / "b.csv").write_text("y\n2\n", encoding="utf-8")
+    ctx = load_csv_context(tmp_path)
+    assert "a" in ctx and "b" in ctx
+
+
+def test_load_csv_empty_file(tmp_path: Path):
+    (tmp_path / "empty.csv").write_text("", encoding="utf-8")
+    ctx = load_csv_context(tmp_path)
+    assert ctx == {"empty": []}
+
+
+def test_load_csv_blank_lines_skipped(tmp_path: Path):
+    (tmp_path / "data.csv").write_text("name\nAlice\n\nBob\n", encoding="utf-8")
+    ctx = load_csv_context(tmp_path)
+    assert len(ctx["data"]) == 2
+
+
+def test_load_csv_from_file_path(tmp_path: Path):
+    (tmp_path / "data.csv").write_text("col\nval\n", encoding="utf-8")
+    f = tmp_path / "doc.md"
+    f.write_text("")
+    ctx = load_csv_context(f)
+    assert "data" in ctx
+
+
+# --- load_context ---
+
+
+def test_load_context_merges_json_and_csv(tmp_path: Path):
+    (tmp_path / "config.json").write_text('{"env": "prod"}', encoding="utf-8")
+    (tmp_path / "people.csv").write_text("name\nAlice\n", encoding="utf-8")
+    ctx = load_context(tmp_path)
+    assert "config" in ctx and "people" in ctx
+
+
+def test_load_context_conflict_raises(tmp_path: Path):
+    (tmp_path / "data.json").write_text('{"key": "val"}', encoding="utf-8")
+    (tmp_path / "data.csv").write_text("col\nval\n", encoding="utf-8")
+    with pytest.raises(ValueError, match="data"):
+        load_context(tmp_path)

mddoco-2.0.0/src/mddoco/__init__.py

@@ -1 +0,0 @@
-__version__ = "2.0.0"

mddoco-2.0.0/src/mddoco/pdf.py

@@ -1,39 +0,0 @@
-import tempfile
-from pathlib import Path
-
-
-def html_to_pdf(html_content: str, dest: Path) -> None:
-    """Render an HTML string to a PDF file using a headless Chromium browser.
-
-    Navigates via a temporary file:// URL so that external resources (CDN
-    scripts, Mermaid.js, etc.) load correctly before the page is printed.
-    """
-    try:
-        from playwright.sync_api import sync_playwright
-    except ImportError:
-        raise RuntimeError(
-            "Playwright is required for PDF output. "
-            "Run: pip install playwright && playwright install chromium"
-        )
-
-    with tempfile.NamedTemporaryFile(
-        suffix=".html", delete=False, mode="w", encoding="utf-8"
-    ) as f:
-        f.write(html_content)
-        tmp_path = Path(f.name)
-
-    try:
-        with sync_playwright() as p:
-            browser = p.chromium.launch()
-            page = browser.new_page()
-            page.goto(tmp_path.as_uri(), wait_until="networkidle")
-            # If Paged.js is present, wait for it to finish paginating before
-            # capturing — networkidle fires before its JS layout pass completes.
-            page.wait_for_function(
-                "typeof window.PagedPolyfill === 'undefined'"
-                " || !!document.querySelector('.pagedjs_pages')"
-            )
-            page.pdf(path=str(dest), format="A4", print_background=True)
-            browser.close()
-    finally:
-        tmp_path.unlink(missing_ok=True)

mddoco-2.0.0/src/mddoco/preprocessor.py

@@ -1,32 +0,0 @@
-import json
-from pathlib import Path
-
-from jinja2 import Environment, FileSystemLoader
-
-
-def load_json_context(input_path: Path) -> dict:
-    """Load all *.json files from the input directory into a template context dict.
-
-    The stem of each JSON file becomes the variable name in the context.
-    E.g. report.json → available as ``report`` inside .md.j2 templates.
-    """
-    directory = input_path if input_path.is_dir() else input_path.parent
-    context: dict = {}
-    for json_file in sorted(directory.glob("*.json")):
-        try:
-            data = json.loads(json_file.read_text(encoding="utf-8"))
-        except json.JSONDecodeError as exc:
-            raise ValueError(f"Invalid JSON in {json_file.name}: {exc}") from exc
-        context[json_file.stem] = data
-    return context
-
-
-def render_j2(path: Path, context: dict) -> str:
-    """Render a .md.j2 Jinja2 template and return the resulting Markdown text."""
-    env = Environment(
-        loader=FileSystemLoader(str(path.parent)),
-        autoescape=False,
-        keep_trailing_newline=True,
-    )
-    template = env.get_template(path.name)
-    return template.render(**context)