munchboka-edutools 0.1.13__py3-none-any.whl

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,
+    }

munchboka_edutools/directives/ggb_popup.py

@@ -0,0 +1,165 @@
+"""
+GeoGebra popup directive for creating interactive GeoGebra applets in dialog windows.
+
+This directive creates a button that opens a GeoGebra Classic applet in a
+draggable, resizable dialog window using jQuery UI.
+
+Usage:
+    Basic usage with defaults (700x500 window):
+    ```{ggb-popup}
+    ```
+
+    Custom size and text:
+    ```{ggb-popup} 800 600 "Open Calculator" "GeoGebra Calculator"
+    ```
+
+    With options:
+    ```{ggb-popup} 900 700 "Open Geometry" "Geometry Window"
+    :perspective: G
+    :menubar: true
+    :layout: sidebar
+    ```
+
+Arguments (all optional):
+    1. Width (default: 700) - Width of the GeoGebra applet in pixels
+    2. Height (default: 500) - Height of the GeoGebra applet in pixels
+    3. Button text (default: "Åpne Geogebra‑vindu") - Text shown on the button
+    4. Dialog title (default: "Geogebra‑vindu") - Title of the dialog window
+
+Options:
+    - perspective: GeoGebra perspective/view (default: "AG")
+      Common values: "AG" (Algebra & Graphics), "G" (Geometry), "GS" (Graphing), "CAS"
+    - menubar: Show menu bar (default: "false") - "true" or "false"
+    - layout: Layout style (default: none) - Use "sidebar" to wrap in sidebar-cas div
+
+Features:
+    - Draggable and resizable dialog window
+    - GeoGebra Classic applet with full features
+    - Responsive sizing when dialog is resized
+    - Centered on screen when opened
+    - jQuery UI styling
+"""
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+import uuid
+
+
+class GGBPopUpDirective(SphinxDirective):
+    """
+    Directive for creating GeoGebra popup windows.
+
+    Creates a button that opens a GeoGebra Classic applet in a jQuery UI dialog.
+    """
+
+    required_arguments = 0
+    optional_arguments = 4  # width, height, button text, dialog title
+    final_argument_whitespace = True
+    has_content = False
+    option_spec = {
+        "layout": lambda arg: arg,  # e.g., "sidebar"
+        "menubar": lambda arg: arg,  # e.g., "true" or "false"
+        "perspective": lambda arg: arg,  # e.g., "GS"
+    }
+
+    def run(self):
+        """Generate HTML for the GeoGebra popup."""
+        # 1 » Parse arguments
+        width = int(self.arguments[0]) if len(self.arguments) > 0 else 700
+        height = int(self.arguments[1]) if len(self.arguments) > 1 else 500
+
+        button_text = self.arguments[2] if len(self.arguments) > 2 else "Åpne Geogebra‑vindu"
+        dialog_title = self.arguments[3] if len(self.arguments) > 3 else "Geogebra‑vindu"
+
+        menubar = self.options.get("menubar", "false")
+
+        perspective = self.options.get("perspective", "AG").strip()
+
+        # 2 » Generate unique IDs
+        cid = f"ggb-geogebra-{uuid.uuid4().hex[:8]}"
+        dialog_id = f"dialog-{cid}"
+        button_id = f"button-{cid}"
+
+        # 3 » Handle layout option
+        layout = self.options.get("layout", "").strip().lower()
+        use_sidebar = layout == "sidebar"
+
+        wrapper_start = '<div class="sidebar-cas">' if use_sidebar else ""
+        wrapper_end = "</div>" if use_sidebar else ""
+
+        # 4 » Generate HTML content
+        html = f"""
+{wrapper_start}
+<meta name="viewport" content="width=device-width, initial-scale=1">
+
+<button id="{button_id}" class="ggb-cas-button">{button_text}</button>
+<div id="{dialog_id}" title="{dialog_title}" style="display:none;">
+    <div id="{cid}" class="ggb-window"></div>
+</div>
+
+<style>
+.ui-resizable-handle {{ min-width:16px;min-height:16px; }}
+.ui-dialog-content{{padding:0!important;}}
+.ggb-window       {{width:100%!important;height:100%!important;box-sizing:border-box;}}
+.ggb-cas-button   {{margin-top: 1em; margin-bottom: 1em;}}
+</style>
+
+<script>
+(function() {{
+  $(function() {{
+    let ggbReady = false;
+
+    function applySize() {{
+      if (!ggbReady) return;
+      const w = $("#{cid}").width(),
+            h = $("#{cid}").height();
+      window.ggbApplet.setSize(Math.round(w), Math.round(h));
+    }}
+
+    $("#{dialog_id}").dialog({{
+      autoOpen: false,
+      width: {width+40}, height: {height+80},
+      resizable: true, draggable: true,
+      position: {{ my: "center", at: "center", of: window }},
+      resize: () => window.requestAnimationFrame(applySize),
+      open: function() {{
+        if (!ggbReady) {{
+          new GGBApplet({{
+            appName: "classic", id: "{cid}",
+            width: {width}, height: {height},
+            perspective: "{perspective}", language: "nb",
+            showToolBar: true, showAlgebraInput: true,
+            borderRadius: 8, enableRightClick: true, showKeyboardOnFocus: false,
+            showMenuBar: {menubar},
+            appletOnLoad: () => {{ ggbReady = true; applySize(); }}
+          }}, true).inject("{cid}");
+        }} else {{
+          applySize();
+        }}
+      }}
+    }});
+
+    $("#{button_id}").button()
+      .on("click touchend pointerup", e => {{
+        e.preventDefault();
+        $("#{dialog_id}").dialog("open");
+      }});
+  }});
+}})();
+</script>
+{wrapper_end}
+        """
+        return [nodes.raw("", html, format="html")]
+
+
+def setup(app):
+    """Register the ggb-popup directive with Sphinx."""
+    app.add_directive("ggb-popup", GGBPopUpDirective)
+    # Also register without hyphen for MyST compatibility
+    app.add_directive("ggbpopup", GGBPopUpDirective)
+
+    return {
+        "version": "0.1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }