munchboka-edutools 0.1.13__py3-none-any.whl

munchboka_edutools/directives/horner.py

@@ -0,0 +1,324 @@
+"""
+Horner scheme (synthetic division) directive for Sphinx/Jupyter Book.
+
+Generates SVG visualizations of Horner's method/synthetic division using LaTeX.
+"""
+
+import os
+import shutil
+import hashlib
+import re
+import uuid
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.util.docutils import SphinxDirective
+
+
+def _hash_key(*parts):
+    """Generate a hash key from multiple parts for caching."""
+    h = hashlib.sha1()
+    for p in parts:
+        if p is None:
+            p = "__NONE__"
+        h.update(str(p).encode("utf-8"))
+        h.update(b"||")
+    return h.hexdigest()[:12]
+
+
+def synthetic_div(
+    fname: str,
+    p: str,
+    x: float,
+    stage: int = 12,
+    svg: bool = True,
+    tutor: bool = False,
+):
+    """
+    Generate Horner scheme (synthetic division) figure using LaTeX.
+
+    Args:
+        fname: Base filename (without extension)
+        p: Polynomial as string (e.g., "x^3 + 2x^2 - 3x - 6")
+        x: Value to evaluate at
+        stage: Stage number for step-by-step display (default: 12 = complete)
+        svg: If True, convert to SVG; otherwise keep as PDF
+        tutor: If True, enable tutor mode with step-by-step guidance
+    """
+    if not tutor:
+        div_cmd = r"\polyhornerscheme[x={x}, resultstyle=\color{red}, showvar=true]{{p}}"
+        div_cmd = div_cmd.replace("{p}", p).replace("{x}", str(x))
+    else:
+        div_cmd = r"\polyhornerscheme[x={x}, stage={stage}, tutor=true, tutorlimit=12, resultstyle=\color{red}, showvar=true]{{p}}"
+        div_cmd = div_cmd.replace("{p}", p).replace("{x}", str(x)).replace("{stage}", str(stage))
+
+    s = f"""\\documentclass{{standalone}}
+\\usepackage{{polynom}}
+\\usepackage{{xcolor}}
+\\begin{{document}}
+{div_cmd}
+\\end{{document}}
+    """
+
+    with open("tmp.tex", "w") as f:
+        f.write(s)
+
+    os.system("pdflatex tmp.tex")
+    if fname.endswith(".svg"):
+        fname = fname.strip(".svg")
+
+    if svg:
+        os.system(f"pdf2svg tmp.pdf {fname}.svg")
+    else:
+        os.system(f"mv tmp.pdf {fname}.pdf")
+
+    os.system("rm tmp.*")
+
+
+class HornerDirective(SphinxDirective):
+    """
+    Generate (and cache) a Horner (synthetic division) scheme as inline SVG.
+
+    Usage (MyST):
+
+    ```
+    ::::{horner}
+    :p: x^3 + 2x^2 - 3x - 6
+    :x: 1
+    :stage: 2      # optional
+    :width: 60%    # optional
+
+    Optional caption here.
+    ::::
+    ```
+
+    Or classic reStructuredText:
+
+    ```
+    .. horner::
+       :p: x^3 + 2x^2 - 3x - 6
+       :x: 1
+       :stage: 2
+
+       Optional caption here.
+    ```
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        "p": directives.unchanged_required,
+        "x": directives.unchanged_required,
+        "stage": directives.nonnegative_int,
+        "tutor": directives.flag,
+        "align": lambda a: directives.choice(a, ["left", "center", "right"]),
+        "class": directives.class_option,
+        "name": directives.unchanged,
+        "nocache": directives.flag,
+        "alt": directives.unchanged,
+        "width": directives.length_or_percentage_or_unitless,
+    }
+
+    def run(self):
+        env = self.state.document.settings.env
+        app = env.app
+
+        # Required options
+        p = self.options.get("p")
+        x_val = self.options.get("x")
+        if p is None or x_val is None:
+            return [
+                self.state_machine.reporter.error(
+                    "Directive 'horner' requires both :p: and :x: options.",
+                    line=self.lineno,
+                )
+            ]
+
+        # Optional options
+        stage = self.options.get("stage", 12)
+        tutor_mode = "tutor" in self.options
+        explicit_name = self.options.get("name")
+
+        # Cache key must include tutor mode so variants don't collide
+        content_hash = _hash_key(p, x_val, stage, int(tutor_mode))
+        base_name = explicit_name or f"horner_{content_hash}"
+
+        # Paths / caching
+        src_dir = app.srcdir
+        rel_dir = os.path.join("_static", "horner")
+        abs_dir = os.path.join(src_dir, rel_dir)
+        os.makedirs(abs_dir, exist_ok=True)
+        svg_filename = f"{base_name}.svg"
+        abs_svg_path = os.path.join(abs_dir, svg_filename)
+
+        regenerate = "nocache" in self.options or not os.path.exists(abs_svg_path)
+        if regenerate:
+            cwd = os.getcwd()
+            try:
+                os.chdir(abs_dir)
+                synthetic_div(
+                    fname=base_name,
+                    p=p,
+                    x=x_val,
+                    stage=stage,
+                    svg=True,
+                    tutor=tutor_mode,
+                )
+            except Exception as e:
+                return [
+                    self.state_machine.reporter.error(
+                        f"Error generating Horner scheme: {e}",
+                        line=self.lineno,
+                    )
+                ]
+            finally:
+                os.chdir(cwd)
+
+        # Post-process: strip explicit width/height if viewBox present for responsiveness
+        try:
+            if os.path.exists(abs_svg_path):
+                with open(abs_svg_path, "r", encoding="utf-8") as f_svg:
+                    raw_tmp = f_svg.read()
+                if "viewBox" in raw_tmp:
+                    cleaned = re.sub(r'\swidth="[^"]+"', "", raw_tmp)
+                    cleaned = re.sub(r'\sheight="[^"]+"', "", cleaned)
+                    if cleaned != raw_tmp:
+                        with open(abs_svg_path, "w", encoding="utf-8") as f_out:
+                            f_out.write(cleaned)
+        except Exception:
+            pass
+
+        if not os.path.exists(abs_svg_path):
+            return [
+                self.state_machine.reporter.error(
+                    (
+                        f"horner: failed to generate SVG '{svg_filename}'. "
+                        "Check that 'pdflatex' and 'pdf2svg' are installed."
+                    ),
+                    line=self.lineno,
+                )
+            ]
+
+        # Track dependency & copy to output for HTML builder
+        env.note_dependency(abs_svg_path)
+        try:
+            out_static = os.path.join(app.outdir, "_static", "horner")
+            os.makedirs(out_static, exist_ok=True)
+            shutil.copy2(abs_svg_path, os.path.join(out_static, svg_filename))
+        except Exception:
+            pass
+
+        # Alt text construction
+        if stage is not None and stage != 12:
+            default_alt = f"Horner's scheme for ({p}) at x={x_val} – stage {stage}"
+        else:
+            default_alt = f"Horner's scheme for ({p}) at x={x_val}"
+        if tutor_mode:
+            default_alt += " (tutor mode)"
+        alt = self.options.get("alt", default_alt)
+
+        width_opt = self.options.get("width")
+        percentage_width = isinstance(width_opt, str) and width_opt.strip().endswith("%")
+
+        # Read generated SVG
+        try:
+            with open(abs_svg_path, "r", encoding="utf-8") as f_svg:
+                raw_svg = f_svg.read()
+        except Exception as e:
+            return [
+                self.state_machine.reporter.error(
+                    f"horner inline: could not read SVG: {e}",
+                    line=self.lineno,
+                )
+            ]
+
+        # Ensure unique IDs per embedding
+        def _uniquify_ids(svg_text: str, prefix: str) -> str:
+            ids = set(re.findall(r'\bid="([^"]+)"', svg_text))
+            if not ids:
+                return svg_text
+            mapping = {old: f"{prefix}{old}" for old in ids}
+            for old, new in mapping.items():
+                svg_text = re.sub(rf'\bid="{re.escape(old)}"', f'id="{new}"', svg_text)
+            for old, new in mapping.items():
+                svg_text = re.sub(
+                    rf'(?:xlink:)?href="#?{re.escape(old)}"', f'href="#{new}"', svg_text
+                )
+                svg_text = re.sub(
+                    rf'xlink:href="#?{re.escape(old)}"',
+                    f'xlink:href="#{new}"',
+                    svg_text,
+                )
+            for old, new in mapping.items():
+                svg_text = re.sub(rf"url\(#\s*{re.escape(old)}\s*\)", f"url(#{new})", svg_text)
+            for old, new in mapping.items():
+                svg_text = re.sub(rf"#({re.escape(old)})\b", f"#{new}", svg_text)
+            return svg_text
+
+        unique_prefix = f"hnr_{_hash_key(p, x_val, stage, int(tutor_mode))}_{uuid.uuid4().hex[:6]}_"
+        raw_svg = _uniquify_ids(raw_svg, unique_prefix)
+
+        # Augment root <svg> (unified width handling)
+        def _augment(match):
+            tag = match.group(0)
+            if "class=" not in tag:
+                tag = tag[:-1] + ' class="horner-inline-svg"' + ">"
+            else:
+                tag = tag.replace('class="', 'class="horner-inline-svg ')
+            if alt and "aria-label=" not in tag:
+                tag = tag[:-1] + f' role="img" aria-label="{alt}"' + ">"
+            if width_opt:
+                w_raw = width_opt.strip()
+                if percentage_width:
+                    w_css = w_raw
+                    margin = "margin:0 auto;" if "margin:" not in tag else ""
+                    style_frag = f"width:{w_css}; height:auto; display:block; {margin}".strip()
+                else:
+                    w_css = (w_raw + "px") if w_raw.isdigit() else w_raw
+                    style_frag = f"width:{w_css}; height:auto; display:block;"
+                if "style=" in tag:
+                    tag = re.sub(
+                        r'style="([^"]*)"',
+                        lambda m: f'style="{m.group(1)}; {style_frag}"',
+                        tag,
+                        count=1,
+                    )
+                else:
+                    tag = tag[:-1] + f' style="{style_frag}"' + ">"
+            return tag
+
+        raw_svg = re.sub(r"<svg\b[^>]*>", _augment, raw_svg, count=1)
+
+        # Build docutils figure
+        figure = nodes.figure()
+        figure.setdefault("classes", []).extend(["adaptive-figure", "horner-figure", "no-click"])
+
+        raw_node = nodes.raw("", raw_svg, format="html")
+        raw_node.setdefault("classes", []).extend(["horner-image", "no-click", "no-scaled-link"])
+        figure += raw_node
+
+        extra_classes = self.options.get("class")
+        if extra_classes:
+            figure["classes"].extend(extra_classes)
+        figure["align"] = self.options.get("align", "center")
+
+        if self.content:
+            caption_text = "\n".join(self.content)
+            caption_node = nodes.caption()
+            caption_node += nodes.Text(caption_text)
+            figure += caption_node
+
+        if explicit_name:
+            self.add_name(figure)
+
+        return [figure]
+
+
+def setup(app):
+    app.add_directive("horner", HornerDirective)
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

munchboka_edutools/directives/interactive_code.py

@@ -0,0 +1,75 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+import re
+import uuid
+
+
+class InteractiveCodeDirective(Directive):
+    has_content = True
+    required_arguments = 0  # The unique identifier
+    optional_arguments = 1
+    final_argument_whitespace = True
+    option_spec = {
+        "lang": directives.unchanged,
+        "predict": directives.flag,
+    }
+
+    def run(self):
+        # Get the unique identifier from arguments
+        # Generate a unique identifier or use the provided one
+        if self.arguments:
+            identifier = self.arguments[0]
+        else:
+            identifier = f"code-{uuid.uuid4().hex[:8]}"
+
+        container_id = f"container-{identifier}"
+
+        # Get code content from the directive content
+        code_content = "\n".join(self.content)
+
+        # Escape code for JavaScript
+        escaped_code = code_content.replace("`", "\\`").replace("$", "\\$")
+
+        is_prediction = "predict" in self.options
+        # Choose the appropriate function based on the predict flag
+        function_name = "makePredictionInteractiveCode" if is_prediction else "makeInteractiveCode"
+
+        # Create the HTML with the template
+        html = f"""
+        <div id="{container_id}"></div>
+        <script type="text/javascript">
+            document.addEventListener("DOMContentLoaded", () => {{
+                const code = 
+`{escaped_code}`;
+
+                {function_name}(
+                    "{container_id}",
+                    code,
+                );
+            }});
+        </script>
+        """
+
+        raw_node = nodes.raw("", html, format="html")
+        return [raw_node]
+
+
+def setup(app):
+    app.add_directive("interactive-code", InteractiveCodeDirective)
+
+    # Ensure assets loaded even if submodule loaded directly
+    try:
+        app.add_css_file("munchboka/css/interactive_code.css")
+        app.add_js_file("munchboka/js/interactiveCode/interactiveCodeSetup.js")
+        app.add_js_file("munchboka/js/interactiveCode/codeEditor.js")
+        app.add_js_file("munchboka/js/interactiveCode/pythonRunner.js")
+        app.add_js_file("munchboka/js/interactiveCode/workerManager.js")
+        app.add_js_file("munchboka/js/interactiveCode/turtleCode.js")
+    except Exception:
+        pass
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

munchboka_edutools/directives/jeopardy.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+import html as _html
+import json
+import os
+import re
+import uuid
+from typing import Any, Dict, List
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.util.docutils import SphinxDirective
+
+
+class JeopardyDirective(SphinxDirective):
+    has_content = True
+    required_arguments = 0
+    option_spec = {
+        "teams": directives.unchanged,
+    }
+
+    def run(self):
+        self.board_id = uuid.uuid4().hex
+        container_id = f"jeopardy-{self.board_id}"
+
+        data = self._parse_board()
+
+        # Compute relative prefix to _static (if needed later)
+        source_file = self.state.document["source"]
+        source_dir = os.path.dirname(source_file)
+        app_src_dir = self.env.srcdir
+        depth = os.path.relpath(source_dir, app_src_dir).count(os.sep)
+        rel_prefix = "../" * (depth + 1)
+
+        # Prepare config both as data-config (HTML-escaped) and inline JSON script inside the container
+        cfg_str_attr = _html.escape(json.dumps(data, ensure_ascii=False), quote=True)
+        json_str = json.dumps(data, ensure_ascii=False)
+
+        # Include KaTeX like the quiz/legacy extension to ensure math renders
+        html = f"""
+        <div id="{container_id}" class=\"jeopardy-container\" lang=\"no\" data-config=\"{cfg_str_attr}\">
+          <script type=\"application/json\" class=\"jeopardy-data\">{json_str}</script>
+        </div>
+        <link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css\">
+        <script defer src=\"https://cdn.jsdelivr.net/npm/katex/dist/katex.min.js\"></script>
+        <script defer src=\"https://cdn.jsdelivr.net/npm/katex/dist/contrib/auto-render.min.js\"></script>
+        """
+        return [nodes.raw("", html, format="html")]
+
+    def _parse_board(self) -> Dict[str, Any]:
+        teams_opt = self.options.get("teams")
+        try:
+            teams = max(1, int(str(teams_opt).strip())) if teams_opt is not None else 2
+        except Exception:
+            teams = 2
+
+        categories: List[Dict[str, Any]] = []
+        current_cat: Dict[str, Any] | None = None
+        current_tile: Dict[str, Any] | None = None
+        current_section: str | None = None
+        values_set = set()
+
+        def flush_tile():
+            nonlocal current_tile
+            if current_cat is not None and current_tile is not None:
+                for k in ("question", "answer"):
+                    if current_tile.get(k) is None:
+                        current_tile[k] = ""
+                (current_cat.setdefault("tiles", [])).append(current_tile)
+            current_tile = None
+
+        for raw in self.content:
+            line = self._process_figures(raw)
+            if line is None:
+                line = raw
+            s = line.rstrip("\n")
+
+            m = re.match(r"^\s*Category\s*:\s*(.+?)\s*$", s, flags=re.IGNORECASE)
+            if m:
+                flush_tile()
+                current_cat = {"name": m.group(1).strip(), "tiles": []}
+                categories.append(current_cat)
+                current_section = None
+                continue
+
+            m = re.match(r"^\s*(\d+)\s*:\s*$", s)
+            if m and current_cat is not None:
+                flush_tile()
+                v = int(m.group(1))
+                values_set.add(v)
+                current_tile = {"value": v, "question": "", "answer": ""}
+                current_section = None
+                continue
+
+            m = re.match(r"^\s*Q\s*:\s*(.*)$", s, flags=re.IGNORECASE)
+            if m and current_tile is not None:
+                current_section = "Q"
+                current_tile["question"] = (current_tile.get("question") or "") + m.group(1)
+                continue
+            m = re.match(r"^\s*A\s*:\s*(.*)$", s, flags=re.IGNORECASE)
+            if m and current_tile is not None:
+                current_section = "A"
+                current_tile["answer"] = (current_tile.get("answer") or "") + m.group(1)
+                continue
+
+            if current_section == "Q" and current_tile is not None:
+                current_tile["question"] = (current_tile.get("question") or "") + "\n" + s
+                continue
+            if current_section == "A" and current_tile is not None:
+                current_tile["answer"] = (current_tile.get("answer") or "") + "\n" + s
+                continue
+
+        flush_tile()
+
+        values = sorted(values_set)
+        for cat in categories:
+            by_val = {t.get("value"): t for t in (cat.get("tiles") or [])}
+            cat["tiles"] = [by_val.get(v) for v in values if v in by_val]
+
+        for cat in categories:
+            for t in cat.get("tiles") or []:
+                for key in ("question", "answer"):
+                    s = t.get(key) or ""
+                    t[key] = self._process_code_blocks(s)
+
+        return {"teams": teams, "categories": categories, "values": values}
+
+    def _process_figures(self, text):
+        import shutil
+        import json as _json
+
+        if not hasattr(self, "_image_counter"):
+            self._image_counter = 0
+
+        def _parse_figure_options(alt_text):
+            opts: Dict[str, Any] = {}
+            s = (alt_text or "").strip()
+
+            def parse_pairs(text: str):
+                for m in re.finditer(r'(\w+)\s*=\s*(?:"([^"]*)"|\'([^\']*)\'|([^\s}]+))', text):
+                    val = m.group(2) or m.group(3) or m.group(4) or ""
+                    opts[m.group(1)] = val
+
+            if s.startswith("{") and s.endswith("}"):
+                inner = s[1:-1].strip()
+                ok = False
+                try:
+                    js = s
+                    js = re.sub(r"(\w+)\s*:", r'"\\1":', js)
+                    js = re.sub(r':\s*([^",}]+)', r': "\\1"', js)
+                    opts.update(_json.loads(js))
+                    ok = True
+                except Exception:
+                    ok = False
+                if not ok:
+                    parse_pairs(inner)
+            else:
+                parse_pairs(s)
+                if not opts and s:
+                    opts["alt"] = s
+            return opts
+
+        def _build_figure_html(html_img_path, options):
+            user_opts = dict(options or {})
+            user_class = user_opts.pop("class", "").strip()
+            classes = "jeopardy-image adaptive-figure" + (f" {user_class}" if user_class else "")
+
+            alt_text = user_opts.pop("alt", "Figure")
+            title = user_opts.pop("title", None)
+            width = user_opts.pop("width", None)
+            height = user_opts.pop("height", None)
+            extra_style = user_opts.pop("style", None)
+
+            def _normalize_wh(val: Any) -> str:
+                s = str(val).strip()
+                if re.fullmatch(r"\d+(?:\.\d+)?", s):
+                    return f"{s}px"
+                s = re.sub(r"\s+(?=(px|%|em|rem|vh|vw)$)", "", s)
+                return s
+
+            styles: List[str] = []
+            if width is not None:
+                styles.append(f"width: {_normalize_wh(width)};")
+            if height is not None:
+                styles.append(f"height: {_normalize_wh(height)};")
+            if extra_style:
+                styles.append(str(extra_style))
+
+            attrs = [f'src="{html_img_path}"', f'class="{classes}"', f'alt="{alt_text}"']
+            if title:
+                attrs.append(f'title="{title}"')
+            if styles:
+                style_str = " ".join(styles)
+                attrs.append(f'style="{style_str}"')
+            for k, v in user_opts.items():
+                if k not in {"src", "class", "alt", "title", "width", "height", "style"}:
+                    attrs.append(f'{k}="{v}"')
+            img = f"<img {' '.join(attrs)} >"
+            return f'<div class="jeopardy-image-container">{img}</div>'
+
+        def replace(m):
+            alt_or_opts = m.group(1).strip()
+            raw_src = m.group(2)
+            self._image_counter += 1
+            options = _parse_figure_options(alt_or_opts)
+
+            source_file = self.state.document["source"]
+            source_dir = os.path.dirname(source_file)
+            app_src_dir = self.env.srcdir
+
+            abs_fig_src = os.path.normpath(os.path.join(source_dir, raw_src))
+            if not os.path.exists(abs_fig_src):
+                return f'<img src="{raw_src}" class="jeopardy-image adaptive-figure" alt="Figure (missing)">'
+
+            relative_doc_path = os.path.relpath(source_dir, app_src_dir)
+            figure_dest_dir = os.path.join(app_src_dir, "_static", "figurer", relative_doc_path)
+            os.makedirs(figure_dest_dir, exist_ok=True)
+
+            rel_path_from_source = os.path.relpath(abs_fig_src, source_dir)
+            safe_path = rel_path_from_source.replace(os.sep, "_").replace("/", "_")
+            base, ext = os.path.splitext(safe_path)
+            fig_filename = f"{self.board_id}_img{self._image_counter}_{base}{ext}"
+            fig_dest_path = os.path.join(figure_dest_dir, fig_filename)
+            shutil.copy2(abs_fig_src, fig_dest_path)
+
+            depth = os.path.relpath(source_dir, app_src_dir).count(os.sep)
+            rel_prefix = "../" * (depth + 1)
+            html_img_path = f"{rel_prefix}_static/figurer/{relative_doc_path}/{fig_filename}"
+            return _build_figure_html(html_img_path, options)
+
+        return re.sub(r"!\[([^\]]*)\]\(([^)]+)\)", replace, text)
+
+    def _process_code_blocks(self, text: str) -> str:
+        def replace_newlines(match):
+            code = match.group(2).replace("\\n", "\n")
+            lang = match.group(1)
+            return f'<pre><code class="{lang}">{code}</code></pre>'
+
+        pattern = r'<pre><code class="([\w-]+)">(.*?)</code></pre>'
+        return re.sub(pattern, replace_newlines, text, flags=re.DOTALL)
+
+
+def setup(app):
+    app.add_directive("jeopardy", JeopardyDirective)
+    # Ensure assets loaded even if submodule loaded directly
+    try:
+        app.add_css_file("munchboka/css/jeopardy.css")
+        app.add_js_file("munchboka/js/jeopardy.js")
+        app.add_css_file("munchboka/css/general_style.css")
+    except Exception:
+        pass
+    return {"version": "0.1", "parallel_read_safe": True, "parallel_write_safe": True}