munchboka-edutools 0.1.13__py3-none-any.whl

munchboka_edutools/directives/poly_icon.py

@@ -0,0 +1,111 @@
+"""
+Polynomial function shape icon role for inline SVG icons.
+
+This role allows you to insert icons representing different polynomial function shapes.
+The icons help visualize the general shape of polynomial functions.
+
+Usage:
+    A quadratic function with positive leading coefficient has a {poly-icon}`smile` shape.
+
+    A cubic function with negative leading coefficient has a {poly-icon}`cubicdown` shape.
+
+Available icons:
+    - smile: U-shaped (parabola opening upward, like a smile)
+    - frown: ∩-shaped (parabola opening downward, like a frown)
+    - cubicup: Cubic function starting low and ending high (∪∩ shape)
+    - cubicdown: Cubic function starting high and ending low (∩∪ shape)
+
+The icons are rendered as inline images with appropriate alt text.
+"""
+
+from docutils import nodes
+from docutils.parsers.rst import roles
+
+
+# Custom node for polynomial icons
+class poly_icon_node(nodes.Inline, nodes.Element):
+    """Custom node for polynomial icons."""
+
+    pass
+
+
+def poly_icon_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    """
+    Custom role for polynomial function shape icons.
+
+    Usage: {poly-icon}`smile`
+
+    This generates a custom node that will be rendered with relative paths.
+    """
+    # Clean up the icon name (remove any extra whitespace)
+    icon_name = text.strip().lower()
+
+    # Validate icon name
+    valid_icons = ["smile", "frown", "cubicup", "cubicdown"]
+    if icon_name not in valid_icons:
+        msg = inliner.reporter.error(
+            f'Invalid poly-icon name "{icon_name}". Must be one of: {", ".join(valid_icons)}',
+            line=lineno,
+        )
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+
+    # Create our custom node
+    node = poly_icon_node()
+    node["icon_name"] = icon_name
+    node["classes"] = ["inline-image"]
+
+    return [node], []
+
+
+def visit_poly_icon_html(self, node):
+    """HTML visitor for poly_icon_node - generates relative path."""
+    icon_name = node["icon_name"]
+
+    # Get the relative path from current document to _static directory
+    # self.builder.current_docname is like "examples/poly_icon"
+    # We want path from there to ../_static/munchboka/icons/polyicons/
+    from os.path import dirname
+
+    # Current document directory depth
+    doc_dir = dirname(self.builder.current_docname) if "/" in self.builder.current_docname else ""
+
+    # Calculate relative path
+    if doc_dir:
+        # For documents in subdirectories like "examples/poly_icon"
+        depth = doc_dir.count("/") + 1
+        rel_prefix = "../" * depth
+    else:
+        # For top-level documents
+        rel_prefix = ""
+
+    img_path = f"{rel_prefix}_static/munchboka/icons/polyicons/{icon_name}.svg"
+
+    # Generate the HTML with relative path
+    html = f'<img src="{img_path}" alt="{icon_name} polynomial icon" class="inline-image" />'
+    self.body.append(html)
+    raise nodes.SkipNode
+
+
+def depart_poly_icon_html(self, node):
+    """Depart function (not needed as we raise SkipNode)."""
+    pass
+
+
+def setup(app):
+    """Setup function to register the role with Sphinx."""
+    # Register the custom node
+    app.add_node(
+        poly_icon_node,
+        html=(visit_poly_icon_html, depart_poly_icon_html),
+    )
+
+    # Register the role with both hyphenated and unhyphenated names
+    roles.register_local_role("poly-icon", poly_icon_role)
+    roles.register_local_role("polyicon", poly_icon_role)
+
+    return {
+        "version": "0.1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

munchboka_edutools/directives/polydiv.py

@@ -0,0 +1,344 @@
+"""
+Polynomial long division directive for Sphinx/Jupyter Book.
+
+Generates SVG visualizations of polynomial long 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 polylongdiv(fname: str, p: str, q: str, stage: int = None, svg: bool = True, vars=None):
+    """
+    Generate polynomial long division figure using LaTeX.
+
+    Args:
+        fname: Base filename (without extension)
+        p: Dividend polynomial as string (e.g., "x^3 + 2x^2 - 3x - 6")
+        q: Divisor polynomial as string (e.g., "x - 2")
+        stage: Optional stage number for step-by-step display
+        svg: If True, convert to SVG; otherwise keep as PDF
+        vars: Variable(s) used in polynomials (default: "x")
+    """
+    if not vars:
+        vars = "x"
+
+    # Generate unique temp filenames
+    temp_id = uuid.uuid4().hex[:8]
+    tex_file = f"tmp_{temp_id}.tex"
+    pdf_file = f"tmp_{temp_id}.pdf"
+
+    # Format LaTeX command
+    if stage is None:
+        div_cmd = r"\polylongdiv[style=C, div=:, vars=None]{{p}}{{q}}"
+        div_cmd = div_cmd.replace("{p}", p).replace("{q}", q).replace("None", str(vars))
+    else:
+        div_cmd = r"\polylongdiv[style=C, div=:, stage={stage}]{{p}}{{q}}"
+        div_cmd = div_cmd.replace("{p}", p).replace("{q}", q).replace("{stage}", str(stage))
+
+    # Create LaTeX file
+    s = f"""\\documentclass[border=0.2cm]{{standalone}}
+\\usepackage{{polynom}}
+\\begin{{document}}
+{div_cmd}
+\\end{{document}}
+    """
+
+    # Remove .svg extension properly if present
+    if fname.endswith(".svg"):
+        fname = fname[:-4]
+
+    # Write and process files
+    with open(tex_file, "w") as f:
+        f.write(s)
+
+    os.system(f"pdflatex {tex_file}")
+
+    if svg:
+        os.system(f"pdf2svg {pdf_file} {fname}.svg")
+    else:
+        os.system(f"mv {pdf_file} {fname}.pdf")
+
+    # Cleanup temp files
+    os.system(f"rm tmp_{temp_id}.*")
+
+
+class PolyDivDirective(SphinxDirective):
+    """
+    Generate (and cache) a polynomial long division figure as SVG and embed it.
+
+    Usage (MyST):
+
+    ```
+    ::::{polydiv}
+    :p: x^3 + 2x^2 - 3x - 6
+    :q: x - 2
+    :stage: 2        # optional
+    :vars: x         # optional (default x)
+    :align: center   # optional (left|center|right)
+    :class: small    # optional extra CSS classes on figure
+
+    Optional caption here.
+    ::::
+    ```
+
+    Or classic reStructuredText:
+
+    ```
+    .. polydiv::
+       :p: x^3 + 2x^2 - 3x - 6
+       :q: x - 2
+       :stage: 2
+       :vars: x
+
+       Optional caption here.
+    ```
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        "p": directives.unchanged_required,
+        "q": directives.unchanged_required,
+        "stage": directives.nonnegative_int,
+        "vars": directives.unchanged,
+        "align": lambda a: directives.choice(a, ["left", "center", "right"]),
+        "class": directives.class_option,
+        "name": directives.unchanged,  # optional explicit base filename / ref name
+        "cache": directives.flag,  # include to enable (default on)
+        "nocache": directives.flag,  # include to force regeneration
+        "alt": directives.unchanged,
+        "width": directives.length_or_percentage_or_unitless,
+        # Always inline now; legacy 'inline' option kept (ignored) for backward compatibility
+        "inline": directives.flag,
+    }
+
+    def run(self):
+        """Main directive entry: always inline-embed generated SVG and allow width control & centering."""
+        env = self.state.document.settings.env
+        app = env.app
+
+        # Options
+        p = self.options.get("p")
+        q = self.options.get("q")
+        if p is None or q is None:
+            return [
+                self.state_machine.reporter.error(
+                    "Directive 'polydiv' requires both :p: and :q: options.",
+                    line=self.lineno,
+                )
+            ]
+        stage = self.options.get("stage")
+        vars_opt = self.options.get("vars", "x")
+        explicit_name = self.options.get("name")
+        content_hash = _hash_key(p, q, stage, vars_opt)
+        base_name = explicit_name or f"polydiv_{content_hash}"
+
+        # Paths
+        src_dir = app.srcdir
+        rel_dir = os.path.join("_static", "polydiv")
+        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)
+                polylongdiv(
+                    fname=base_name,
+                    p=p,
+                    q=q,
+                    stage=stage,
+                    vars=vars_opt,
+                )
+            except Exception as e:
+                return [
+                    self.state_machine.reporter.error(
+                        f"Error generating polynomial division: {e}",
+                        line=self.lineno,
+                    )
+                ]
+            finally:
+                os.chdir(cwd)
+
+        # Post-process: strip width/height for responsiveness if viewBox present
+        try:
+            if os.path.exists(abs_svg_path):
+                with open(abs_svg_path, "r", encoding="utf-8") as f_svg:
+                    svg_text_tmp = f_svg.read()
+                if "viewBox" in svg_text_tmp:
+                    cleaned = re.sub(r'\swidth="[^"]+"', "", svg_text_tmp)
+                    cleaned = re.sub(r'\sheight="[^"]+"', "", cleaned)
+                    if cleaned != svg_text_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"polydiv: failed to generate SVG '{svg_filename}'. "
+                        "Check that 'pdflatex' and 'pdf2svg' are installed."
+                    ),
+                    line=self.lineno,
+                )
+            ]
+
+        env.note_dependency(abs_svg_path)
+        try:
+            out_static = os.path.join(app.outdir, "_static", "polydiv")
+            os.makedirs(out_static, exist_ok=True)
+            shutil.copy2(abs_svg_path, os.path.join(out_static, svg_filename))
+        except Exception:
+            pass
+
+        # Alt text
+        if stage is not None:
+            default_alt = f"Polynomial division of ({p}) : ({q}) – stage {stage}"
+        else:
+            default_alt = f"Polynomial division of ({p}) : ({q})"
+        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 final 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"polydiv inline: could not read SVG: {e}",
+                    line=self.lineno,
+                )
+            ]
+
+        # Uniquify IDs to prevent collisions
+        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"pd_{_hash_key(p, q, stage, vars_opt)}_{uuid.uuid4().hex[:6]}_"
+        raw_svg = _uniquify_ids(raw_svg, unique_prefix)
+
+        # Augment root <svg> (single pass handles both percent and fixed widths)
+        def _augment(match):
+            tag = match.group(0)
+            if "class=" not in tag:
+                tag = tag[:-1] + ' class="polydiv-inline-svg"' + ">"
+            else:
+                tag = tag.replace('class="', 'class="polydiv-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:
+                    # percentage width: keep percent, center block
+                    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:
+                    # fixed / unit width: add px if bare number
+                    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)
+
+        figure = nodes.figure()
+        figure.setdefault("classes", []).extend(
+            [
+                "adaptive-figure",
+                "polydiv-figure",
+                "no-click",
+            ]
+        )
+
+        raw_node = nodes.raw("", raw_svg, format="html")
+        raw_node.setdefault("classes", []).extend(
+            [
+                "polydiv-image",
+                "no-click",
+                "no-scaled-link",
+            ]
+        )
+        figure += raw_node
+
+        # Extra classes & alignment
+        extra_classes = self.options.get("class")
+        if extra_classes:
+            figure["classes"].extend(extra_classes)
+        figure["align"] = self.options.get("align", "center")
+
+        # Caption
+        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("polydiv", PolyDivDirective)
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

munchboka_edutools/directives/popup.py

@@ -0,0 +1,245 @@
+"""
+Popup directive and role for creating modal dialogs.
+
+This extension provides two ways to create popups:
+
+1. **Directive**: Creates a button that opens a dialog with content
+2. **Role**: Creates inline text that shows a tooltip/bubble on hover
+
+Directive Usage:
+    ```{popup} Button Text
+    :title: Dialog Title
+    :width: 600
+    :height: 400
+
+    Content goes here. Supports **markdown** and $\\LaTeX$ math.
+    ```
+
+Role Usage:
+    This is {popup}`hover text <tooltip content>` inline.
+
+The popup directive creates a modal dialog using jQuery UI, with automatic
+KaTeX rendering for mathematical expressions. The role creates a simple
+hover bubble for quick information.
+"""
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective, SphinxRole
+from docutils.parsers.rst import directives
+import uuid
+import re
+
+
+class PopupDirective(SphinxDirective):
+    """
+    Directive for creating a button that opens a modal dialog.
+
+    Options:
+        - title: Dialog title (default: "Mer informasjon")
+        - width: Dialog width in pixels (default: 500)
+        - height: Dialog height in pixels or "auto" (default: "auto")
+
+    Arguments:
+        - Button text (optional, default: "Vis mer")
+
+    Content:
+        - The content to display in the dialog (supports MyST markdown)
+    """
+
+    has_content = True
+    option_spec = {
+        "title": directives.unchanged,
+        "width": directives.positive_int,
+        "height": directives.unchanged,
+    }
+    required_arguments = 0
+    optional_arguments = 1  # Button text
+
+    def run(self):
+        # Get button text from arguments or use default
+        button_text = self.arguments[0] if self.arguments else "Vis mer"
+
+        # Get title from options or use default
+        dialog_title = self.options.get("title", "Mer informasjon")
+
+        # Get width and height if specified
+        width = self.options.get("width", 500)
+        height = self.options.get("height", "auto")
+
+        # Generate unique IDs
+        popup_id = f"popup-{uuid.uuid4().hex[:8]}"
+        button_id = f"button-{popup_id}"
+        content_id = f"content-{popup_id}"
+
+        # Process the directive content as markdown
+        content_html = "\n".join(self.content)
+
+        # Create the raw HTML with jQuery UI and KaTeX
+        html = f"""
+<!-- Button to open the popup -->
+<button id="{button_id}" class="popup-button">{button_text}</button>
+
+<!-- Dialog container -->
+<div id="{content_id}" class="popup-content" style="display:none;">
+    {content_html}
+</div>
+
+<!-- Script for KaTeX and dialog setup -->
+<script>
+(function() {{
+    // Function to load scripts sequentially
+    function loadScript(src, id) {{
+        return new Promise((resolve, reject) => {{
+            // Check if script is already loaded
+            if (document.getElementById(id)) {{
+                resolve();
+                return;
+            }}
+            
+            const script = document.createElement('script');
+            script.id = id;
+            script.src = src;
+            script.async = false; // Important: maintain loading order
+            script.onload = () => resolve();
+            script.onerror = () => reject(new Error(`Failed to load script: ${{src}}`));
+            document.head.appendChild(script);
+        }});
+    }}
+    
+    // Function to load stylesheets
+    function loadStylesheet(href, id) {{
+        return new Promise((resolve) => {{
+            if (document.getElementById(id)) {{
+                resolve();
+                return;
+            }}
+            
+            const link = document.createElement('link');
+            link.id = id;
+            link.rel = 'stylesheet';
+            link.href = href;
+            link.onload = resolve;
+            document.head.appendChild(link);
+        }});
+    }}
+
+    // Initialize dialog once everything is loaded
+    function initializeDialog() {{
+        $("#{content_id}").dialog({{
+            autoOpen: false,
+            title: "{dialog_title}",
+            width: {width},
+            dialogClass: "popup-dialog",
+            modal: false,
+            resizable: true,
+            draggable: true,
+            open: function() {{
+                // Safety check to ensure KaTeX is available
+                if (window.katex && window.renderMathInElement) {{
+                    try {{
+                        renderMathInElement(document.getElementById('{content_id}'), {{
+                            delimiters: [
+                                {{left: "$$", right: "$$", display: true}},
+                                {{left: "$", right: "$", display: false}},
+                                {{left: "\\\\(", right: "\\\\)", display: false}},
+                                {{left: "\\\\[", right: "\\\\]", display: true}}
+                            ],
+                            throwOnError: false
+                        }});
+                    }} catch (e) {{
+                        console.error("KaTeX rendering error:", e);
+                    }}
+                }}
+            }}
+        }});
+        
+        // Button click handler
+        $("#{button_id}").on("click", function() {{
+            $("#{content_id}").dialog("open");
+        }});
+    }}
+    
+    // Main initialization function
+    async function initialize() {{
+        try {{
+            // First, load jQuery if not already available
+            if (!window.jQuery) {{
+                await loadScript('https://code.jquery.com/jquery-3.6.0.min.js', 'jquery-script');
+            }}
+            
+            // Then jQuery UI - safer check
+            if (!window.jQuery || typeof window.jQuery.ui === 'undefined') {{
+                await loadScript('https://code.jquery.com/ui/1.13.2/jquery-ui.min.js', 'jquery-ui-script');
+                await loadStylesheet('https://code.jquery.com/ui/1.13.2/themes/base/jquery-ui.css', 'jquery-ui-css');
+            }}
+            
+            // Then KaTeX and auto-render in sequence
+            await loadStylesheet('https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css', 'katex-css');
+            await loadScript('https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js', 'katex-script');
+            await loadScript('https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js', 'katex-auto-render');
+            
+            // Initialize dialog after all scripts are loaded
+            initializeDialog();
+        }} catch (error) {{
+            console.error('Error initializing popup:', error);
+        }}
+    }}
+    
+    // Start initialization when document is ready
+    if (document.readyState === 'loading') {{
+        document.addEventListener('DOMContentLoaded', initialize);
+    }} else {{
+        initialize();
+    }}
+}})();
+</script>
+"""
+        return [nodes.raw("", html, format="html")]
+
+
+class PopupRole(SphinxRole):
+    """
+    Role for creating inline popups/tooltips.
+
+    Usage:
+        {popup}`label <content>`
+
+    The label is what appears in the text, and the content appears
+    in a tooltip/bubble when hovering over the label.
+    """
+
+    def run(self):
+        text = self.text
+        content_html = ""
+
+        # Parse the input: label <content>
+        options_match = re.search(r"<([^>]+)>\s*(?:\(([^)]+)\))?", text)
+        if options_match:
+            label = text[: options_match.start()].strip()
+            content_html = options_match.group(1)
+        else:
+            label = text
+
+        popup_id = f"popup-role-{uuid.uuid4().hex[:8]}"
+
+        html = f"""
+<span class="popup-wrapper" id="{popup_id}">
+  <span class="popup-trigger">{label}</span>
+  <span class="popup-bubble" style="display:none;">{content_html}</span>
+</span>
+"""
+
+        return [nodes.raw("", html, format="html")], []
+
+
+def setup(app):
+    """Setup function to register the directive and role with Sphinx."""
+    # Register the directive and role
+    app.add_directive("popup", PopupDirective)
+    app.add_role("popup", PopupRole())
+
+    return {
+        "version": "0.1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }