munchboka-edutools 0.2.3__py3-none-any.whl

munchboka_edutools/directives/flashcards.py

@@ -0,0 +1,233 @@
+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 FlashcardsDirective(SphinxDirective):
+    has_content = True
+    required_arguments = 0
+    option_spec = {
+        "shuffle": directives.flag,
+        "show_progress": directives.flag,
+        "start_index": directives.nonnegative_int,
+    }
+
+    def run(self):
+        deck_id = uuid.uuid4().hex
+        container_id = f"flashcards-{deck_id}"
+
+        data = self._parse_deck()
+
+        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)
+
+        cfg: Dict[str, Any] = {
+            "cards": data["cards"],
+            "options": {
+                "shuffle": "shuffle" in self.options,
+                "show_progress": "show_progress" in self.options,
+                "start_index": int(self.options.get("start_index", 0) or 0),
+                "staticPrefix": rel_prefix,
+            },
+        }
+
+        cfg_str_attr = _html.escape(json.dumps(cfg, ensure_ascii=False), quote=True)
+        json_str = json.dumps(cfg, ensure_ascii=False)
+
+        html = f"""
+        <div id="{container_id}" class=\"flashcards-container\" data-config=\"{cfg_str_attr}\">
+          <script type=\"application/json\" class=\"flashcards-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_deck(self) -> Dict[str, Any]:
+        cards: List[Dict[str, Any]] = []
+        current: Dict[str, Any] | None = None
+        section: str | None = None
+
+        def flush():
+            nonlocal current
+            if current is not None:
+                for k in ("front", "back"):
+                    if current.get(k) is None:
+                        current[k] = ""
+                cards.append(current)
+            current = 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*Q\s*:\s*(.*)$", s, flags=re.IGNORECASE)
+            if m:
+                flush()
+                current = {"front": m.group(1), "back": ""}
+                section = "front"
+                continue
+
+            m = re.match(r"^\s*A\s*:\s*(.*)$", s, flags=re.IGNORECASE)
+            if m and current is not None:
+                current["back"] = (current.get("back") or "") + m.group(1)
+                section = "back"
+                continue
+
+            if section == "front" and current is not None:
+                current["front"] = (current.get("front") or "") + "\n" + s
+                continue
+            if section == "back" and current is not None:
+                current["back"] = (current.get("back") or "") + "\n" + s
+                continue
+
+        flush()
+
+        for c in cards:
+            for key in ("front", "back"):
+                val = c.get(key) or ""
+                c[key] = self._process_code_blocks(val)
+
+        return {"cards": cards}
+
+    def _process_code_blocks(self, text: str) -> str:
+        def repl(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, repl, text, flags=re.DOTALL)
+
+    def _process_figures(self, text: str):
+        import shutil
+        import json as _json
+
+        if not hasattr(self, "_image_counter"):
+            self._image_counter = 0
+
+        def _parse_figure_options(alt_text: str) -> Dict[str, Any]:
+            opts: Dict[str, Any] = {}
+            s = (alt_text or "").strip()
+
+            def parse_pairs(content: str):
+                for m in re.finditer(
+                    r'(\\w+)\\s*=\\s*(?:"([^"]*)"|\'([^\']*)\'|([^\\s}]+))', content
+                ):
+                    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: str, options: Dict[str, Any]) -> str:
+            user_opts = dict(options or {})
+            user_class = user_opts.pop("class", "").strip()
+            classes = "flashcard-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="flashcard-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="flashcard-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"flash_{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 setup(app):
+    app.add_directive("flashcards", FlashcardsDirective)
+    try:
+        app.add_css_file("munchboka/css/flashcards.css")
+        app.add_js_file("munchboka/js/flashcards.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}

munchboka_edutools/directives/ggb.py

@@ -0,0 +1,209 @@
+"""
+GeoGebra Directive for Munchboka Edutools
+=========================================
+
+This directive embeds interactive GeoGebra applets in the documentation.
+It uses the GeoGebra API to create fully functional mathematics tools
+directly in the browser.
+
+Usage in MyST Markdown:
+    ```{ggb} 720 600
+    :material_id: abcdef123
+    :toolbar: true
+    :menubar: true
+    :algebra: true
+    ```
+
+Or with defaults (empty applet):
+    ```{ggb} 800 600
+    ```
+
+Or with perspective:
+    ```{ggb} 720 600
+    :material_id: xyz789
+    :perspective: graphing
+    ```
+
+Features:
+    - Embed existing GeoGebra materials by ID
+    - Configure toolbar, menubar, and algebra view visibility
+    - Set custom dimensions (width × height)
+    - Multiple perspective options (graphing, geometry, 3d, etc.)
+    - Automatic fullscreen and reset buttons
+    - Norwegian language interface
+
+Arguments:
+    width (optional): Width in pixels (default: 720)
+    height (optional): Height in pixels (default: 600)
+
+Options:
+    material_id (optional): GeoGebra material ID to load
+    toolbar (optional): Show toolbar ("true"/"false", default: "false")
+    menubar (optional): Show menubar ("true"/"false", default: "false")
+    algebra (optional): Show algebra view ("true"/"false", default: "false")
+    perspective (optional): Perspective to use (e.g., "graphing", "geometry", "3d")
+
+Dependencies:
+    - GeoGebra API: Loaded via deployggb.js (already registered in __init__.py)
+    - geogebra-setup.js: Theme management and initialization
+
+Author: René Aasen (ported from matematikk_r1)
+Date: November 2025
+"""
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+from docutils.parsers.rst import directives
+import uuid
+
+
+class GGBDirective(SphinxDirective):
+    """
+    Sphinx directive for embedding interactive GeoGebra applets.
+
+    This directive creates a container div and uses the GeoGebra API
+    (deployggb.js) to inject an interactive mathematics applet.
+
+    Arguments:
+        width (optional): Width in pixels (default: 720)
+        height (optional): Height in pixels (default: 600)
+
+    Options:
+        material_id: GeoGebra material ID (e.g., from geogebra.org/m/xyz)
+        toolbar: Show toolbar ("true"/"false")
+        menubar: Show menubar ("true"/"false")
+        algebra: Show algebra view ("true"/"false")
+        perspective: Perspective to use ("graphing", "geometry", "3d", etc.)
+
+    Examples:
+        Embed a specific GeoGebra material:
+        ```{ggb} 720 600
+        :material_id: abcdef123
+        :toolbar: true
+        :menubar: true
+        :algebra: true
+        ```
+
+        Create an empty applet:
+        ```{ggb} 800 600
+        ```
+
+        Use a specific perspective:
+        ```{ggb} 720 600
+        :material_id: xyz789
+        :perspective: graphing
+        ```
+    """
+
+    required_arguments = 0
+    optional_arguments = 2  # width and height
+    has_content = False
+
+    option_spec = {
+        "material_id": directives.unchanged,
+        "toolbar": directives.unchanged,
+        "menubar": directives.unchanged,
+        "algebra": directives.unchanged,
+        "perspective": directives.unchanged,
+    }
+
+    def run(self):
+        """
+        Generate the HTML for the GeoGebra applet.
+
+        Returns:
+            list: List of docutils nodes (raw HTML node)
+        """
+        # Convert arguments to integers (with defaults if conversion fails)
+        try:
+            width = int(self.arguments[0])
+        except (IndexError, ValueError):
+            width = 720
+        try:
+            height = int(self.arguments[1])
+        except (IndexError, ValueError):
+            height = 600
+
+        # Get options
+        material_id = self.options.get("material_id", None)
+        toolbar = self.options.get("toolbar", "false")
+        menubar = self.options.get("menubar", "false")
+        algebra = self.options.get("algebra", "false")
+        perspective = self.options.get("perspective", None)
+
+        # Format perspective option
+        if perspective:
+            perspective_option = f"perspective: '{perspective}'"
+        else:
+            perspective_option = "'': ''"
+
+        # Format material_id option
+        if material_id:
+            material_id_option = f"material_id: '{material_id}'"
+        else:
+            # If no material_id is provided, enable all controls by default
+            # This creates an empty applet with full functionality
+            material_id_option = "'': ''"
+            toolbar = "true"
+            menubar = "true"
+            algebra = "true"
+
+        # Generate a unique container ID using a short UUID
+        container_id = f"ggb-cas-{uuid.uuid4().hex[:8]}"
+
+        # Create the raw HTML
+        # Note: GeoGebra API (deployggb.js) is already loaded via __init__.py
+        html = f"""
+<div id="{container_id}" style="width: {width}px; height: {height}px;" class="ggb-window"></div>
+<script>
+document.addEventListener("DOMContentLoaded", function() {{
+    var options = {{
+        appName: 'classic',
+        width: {width},
+        height: {height},
+        showToolBar: {toolbar},
+        showAlgebraInput: {algebra},
+        showMenuBar: {menubar},
+        language: 'nb',
+        borderRadius: 8,
+        borderColor: '#000000',
+        showFullscreenButton: true,
+        showResetIcon: true,
+        scale: 1,
+        rounding: 2,
+        showKeyboardOnFocus: false,
+        preventFocus: true,
+        id: '{container_id}',
+        {material_id_option},
+        {perspective_option},
+    }};
+
+    var applet = new GGBApplet(options, true);
+    applet.inject('{container_id}');
+}});
+</script>
+        """
+
+        return [nodes.raw("", html, format="html")]
+
+
+def setup(app):
+    """
+    Setup function to register the directive with Sphinx.
+
+    This function is called automatically by Sphinx when the extension is loaded.
+    It registers the 'ggb' directive for use in documentation.
+
+    Args:
+        app: The Sphinx application instance
+
+    Returns:
+        dict: Extension metadata including version and parallel processing flags
+    """
+    app.add_directive("ggb", GGBDirective)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

munchboka_edutools/directives/ggb_icon.py

@@ -0,0 +1,105 @@
+"""
+GeoGebra icon role for inline SVG icons.
+
+This role allows you to insert GeoGebra tool icons inline in text.
+The icons are SVG files that represent various GeoGebra tools and modes.
+
+Usage:
+    This is the {ggb-icon}`mode_intersect` tool in GeoGebra.
+
+    Click the {ggb-icon}`mode_solve` icon to solve equations.
+
+Available icons:
+    - mode_evaluate: Evaluate/compute icon
+    - mode_extremum: Find extremum (min/max) icon
+    - mode_intersect: Find intersection point icon
+    - mode_nsolve: Numeric solve icon
+    - mode_numeric: Numeric computation icon
+    - mode_point: Point tool icon
+    - mode_solve: Symbolic solve icon
+
+The icons are rendered as inline images with appropriate alt text.
+"""
+
+from docutils import nodes
+from docutils.parsers.rst import roles
+from sphinx.util.osutil import relative_uri
+
+
+# Custom node for GeoGebra icons
+class ggb_icon_node(nodes.Inline, nodes.Element):
+    """Custom node for GeoGebra icons."""
+
+    pass
+
+
+def ggb_icon_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    """
+    Custom role for GeoGebra icons.
+
+    Usage: {ggb-icon}`mode_intersect`
+
+    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()
+
+    # Create our custom node
+    node = ggb_icon_node()
+    node["icon_name"] = icon_name
+    node["classes"] = ["inline-image"]
+
+    return [node], []
+
+
+def visit_ggb_icon_html(self, node):
+    """HTML visitor for ggb_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/ggb_icon"
+    # We want path from there to ../static/munchboka/icons/ggb/
+    from os.path import relpath, dirname, join
+
+    # 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/ggb_icon"
+        depth = doc_dir.count("/") + 1
+        rel_prefix = "../" * depth
+    else:
+        # For top-level documents
+        rel_prefix = ""
+
+    img_path = f"{rel_prefix}_static/munchboka/icons/ggb/{icon_name}.svg"
+
+    # Generate the HTML with relative path
+    html = f'<img src="{img_path}" alt="GeoGebra {icon_name} icon" class="inline-image" />'
+    self.body.append(html)
+    raise nodes.SkipNode
+
+
+def depart_ggb_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(
+        ggb_icon_node,
+        html=(visit_ggb_icon_html, depart_ggb_icon_html),
+    )
+
+    # Register the role with both hyphenated and unhyphenated names
+    roles.register_local_role("ggb-icon", ggb_icon_role)
+    roles.register_local_role("ggbicon", ggb_icon_role)
+
+    return {
+        "version": "0.1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }