munchboka-edutools 0.1.0__py3-none-any.whl

munchboka_edutools/__init__.py

@@ -0,0 +1,182 @@
+from ._version import __version__
+
+import importlib
+import pkgutil
+import os
+from importlib.resources import files
+
+
+def _copy_static(app):
+    """Copy packaged static assets to the builder's _static directory and register defaults."""
+    try:
+        static_root = files(__name__) / "static"
+        if not static_root.exists():
+            return
+
+        out_static_root = os.path.join(app.outdir, "_static", "munchboka")
+        os.makedirs(out_static_root, exist_ok=True)
+
+        # Recursively copy packaged static files
+        for path in static_root.rglob("*"):
+            if path.is_file():
+                rel = path.relative_to(static_root)
+                dest = os.path.join(out_static_root, str(rel))
+                os.makedirs(os.path.dirname(dest), exist_ok=True)
+                with path.open("rb") as src, open(dest, "wb") as dst:
+                    dst.write(src.read())
+
+        # Register a couple of common defaults if present
+        def _register(relpath: str, priority: int = 500):
+            full = os.path.join(out_static_root, relpath)
+            if os.path.exists(full):
+                if relpath.endswith(".css"):
+                    app.add_css_file(f"munchboka/{relpath}", priority=priority)
+                elif relpath.endswith(".js"):
+                    app.add_js_file(f"munchboka/{relpath}", priority=priority)
+
+        # Register CSS files (including CodeMirror CSS for interactive code)
+        app.add_css_file(
+            "https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.2/codemirror.min.css"
+        )
+        # jQuery UI CSS for dialog/popup functionality
+        app.add_css_file("https://code.jquery.com/ui/1.13.2/themes/base/jquery-ui.css")
+        # KaTeX CSS for math rendering (required by pair-puzzle directive)
+        app.add_css_file("https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css")
+        _register("css/admonitions.css")
+        _register("css/dialogue.css")
+        _register("css/figures.css")
+        _register("css/interactive_code.css")
+        _register("css/jeopardy.css")
+        _register("css/general_style.css")
+        _register("css/quiz.css")
+        _register("css/timedQuiz.css")
+        _register("css/cas_popup.css")
+        _register("css/github-light.css")
+        _register("css/github-dark.css")
+        _register("css/github-dark-high-contrast.css")
+        _register("css/pairPuzzle/style.css")
+        _register("css/escapeRoom/escape-room.css")
+        _register("css/parsons/parsonsPuzzle.css")
+
+        # Register JS files with explicit priorities to match matematikk_r1 loading order:
+        # 1. utils.js (early - priority 450)
+        # 2. KaTeX (priority 490-495 - before pair-puzzle)
+        # 3. quiz.js, jeopardy.js (priority 500 - default)
+        # 4. interactive code scripts (priority 500 - default)
+        # 5. pair-puzzle scripts (priority 700-720)
+        # 6. jQuery, jQuery UI, and GeoGebra (priority 800-900)
+        # 7. CodeMirror (last - priority 900)
+        _register("js/utils.js", priority=450)
+        _register("js/casThemeManager.js", priority=480)  # Before jQuery UI for theme handling
+
+        # Add KaTeX before pair-puzzle scripts (which depend on it)
+        app.add_js_file(
+            "https://cdn.jsdelivr.net/npm/katex/dist/katex.min.js",
+            priority=490,
+        )
+        app.add_js_file(
+            "https://cdn.jsdelivr.net/npm/katex/dist/contrib/auto-render.min.js",
+            priority=495,
+        )
+
+        _register("js/jeopardy.js")
+        _register("js/quiz.js")
+        _register("js/timedQuiz/utils.js")
+        _register("js/timedQuiz/multipleChoiceQuestion.js")
+        _register("js/timedQuiz/timedMultipleChoiceQuiz.js")
+        _register("js/interactiveCode/pythonRunner.js")
+        _register("js/interactiveCode/codeEditor.js")
+        _register("js/interactiveCode/interactiveCodeSetup.js")
+        _register("js/interactiveCode/workerManager.js")
+        # Skulpt must be loaded before turtleCode.js (lower priority = loaded first)
+        _register("js/skulpt/skulpt.js", priority=490)
+        _register("js/interactiveCode/turtleCode.js")
+        _register("js/pairPuzzle/draggableItem.js", priority=700)
+        _register("js/pairPuzzle/dropZone.js", priority=710)
+        _register("js/pairPuzzle/game.js", priority=720)
+        _register("js/escapeRoom/escape-room.js", priority=730)
+        _register("js/parsons/parsonsPuzzle.js", priority=740)
+
+        # Add jQuery and jQuery UI for dialog functionality
+        app.add_js_file(
+            "https://code.jquery.com/jquery-3.6.0.min.js",
+            priority=800,
+        )
+        app.add_js_file(
+            "https://code.jquery.com/ui/1.13.2/jquery-ui.min.js",
+            priority=850,
+        )
+
+        # Add highlight.js for syntax highlighting in Parsons puzzles and other directives
+        app.add_css_file(
+            "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/styles/github.min.css",
+            id="highlight-theme-light",
+        )
+        app.add_css_file(
+            "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/styles/github-dark.min.css",
+            id="highlight-theme-dark",
+        )
+        app.add_js_file(
+            "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min.js",
+            priority=855,
+        )
+        _register("js/highlight-init.js", priority=856)
+
+        # Add GeoGebra API
+        app.add_js_file(
+            "https://www.geogebra.org/apps/deployggb.js",
+            priority=860,
+        )
+        _register("js/geogebra-setup.js", priority=870)
+
+        # Add CodeMirror LAST with high priority so it loads at the end
+        app.add_js_file(
+            "https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.2/codemirror.min.js",
+            priority=900,
+        )
+        app.add_js_file(
+            "https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.2/mode/python/python.min.js",
+            priority=900,
+        )
+    except Exception as exc:  # pragma: no cover - non-fatal
+        try:
+            from sphinx.util import logging
+
+            logging.getLogger(__name__).warning(
+                "munchboka_edutools: failed to copy static assets: %s", exc
+            )
+        except Exception:
+            pass
+
+
+def setup(app):
+    """
+    Sphinx entry point for the extension.
+
+    - Copies packaged static assets on builder init
+    - Auto-loads all modules under munchboka_edutools.directives that expose setup(app)
+    """
+    # Ensure packaged static assets are available for HTML builder
+    app.connect("builder-inited", _copy_static)
+
+    # Auto discover and load directive modules
+    pkg_prefix = __name__ + ".directives"
+    try:
+        pkg = importlib.import_module(pkg_prefix)
+        for modinfo in pkgutil.iter_modules(pkg.__path__, pkg_prefix + "."):
+            app.setup_extension(modinfo.name)
+    except Exception as exc:  # pragma: no cover - non-fatal
+        try:
+            from sphinx.util import logging
+
+            logging.getLogger(__name__).warning(
+                "munchboka_edutools: failed to auto-load directives: %s", exc
+            )
+        except Exception:
+            pass
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

munchboka_edutools/_plotmath_shim.py

@@ -0,0 +1,126 @@
+"""Minimal plotmath shim for development and tests.
+
+This is NOT a full replacement for the real plotmath package. It implements
+just enough for the plot directive tests to run:
+- plot(): create fig/ax and set up ticks/grid/limits.
+- annotate(): arrow annotation on current axes.
+- polygon(): draw edges and/or filled polygon.
+- make_bar(): draw a simple double-headed measurement bar.
+- COLORS: a small named color palette.
+
+If the real plotmath is installed, the directive will use that instead.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Tuple, List, Optional
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+COLORS = {
+    "red": "#d62728",
+    "blue": "#1f77b4",
+    "green": "#2ca02c",
+    "orange": "#ff7f0e",
+    "purple": "#9467bd",
+    "teal": "#17becf",
+    "black": "#000000",
+}
+
+
+def plot(
+    functions: List = None,
+    fn_labels: bool = False,
+    xmin: float = -6,
+    xmax: float = 6,
+    ymin: float = -6,
+    ymax: float = 6,
+    xstep: float = 1,
+    ystep: float = 1,
+    ticks: bool = True,
+    grid: bool = True,
+    lw: float = 2.5,
+    alpha: float | None = None,
+    fontsize: int = 20,
+):
+    fig, ax = plt.subplots()
+    ax.set_xlim(xmin, xmax)
+    ax.set_ylim(ymin, ymax)
+    if ticks:
+        try:
+            ax.set_xticks([x for x in frange(xmin, xmax, xstep)])
+            ax.set_yticks([y for y in frange(ymin, ymax, ystep)])
+        except Exception:
+            pass
+    else:
+        ax.set_xticks([])
+        ax.set_yticks([])
+    if grid:
+        ax.grid(True, which="both", alpha=0.25)
+    for spine in ax.spines.values():
+        spine.set_linewidth(1.0)
+    return fig, ax
+
+
+def annotate(xy, xytext, s: str, arc: float = 0.3, fontsize: int = 14):
+    ax = plt.gca()
+    ax.annotate(
+        s,
+        xy=xy,
+        xytext=xytext,
+        arrowprops=dict(arrowstyle="->", connectionstyle=f"arc3,rad={arc}"),
+        fontsize=fontsize,
+    )
+
+
+def polygon(
+    *pts: Tuple[float, float],
+    edges: bool = True,
+    color=None,
+    facecolor=None,
+    alpha=None,
+    show_vertices: bool = False,
+):
+    ax = plt.gca()
+    xs = [p[0] for p in pts] + [pts[0][0]]
+    ys = [p[1] for p in pts] + [pts[0][1]]
+    if facecolor or (color and not edges):
+        ax.fill(xs, ys, color=(facecolor or color), alpha=alpha or 0.1)
+    if edges:
+        ax.plot(xs, ys, color=(color or COLORS.get("black", "black")))
+    if show_vertices:
+        ax.plot(
+            [p[0] for p in pts],
+            [p[1] for p in pts],
+            "o",
+            color=(color or COLORS.get("black", "black")),
+        )
+
+
+def make_bar(xy: Tuple[float, float], length: float, orientation: str = "horizontal"):
+    x, y = xy
+    ax = plt.gca()
+    if orientation.lower().startswith("h"):
+        ax.annotate("", xy=(x, y), xytext=(x + length, y), arrowprops=dict(arrowstyle="|-|"))
+    else:
+        ax.annotate("", xy=(x, y), xytext=(x, y + length), arrowprops=dict(arrowstyle="|-|"))
+
+
+def frange(start: float, stop: float, step: float):
+    vals = []
+    if step == 0:
+        return vals
+    x = start
+    # ensure inclusion of stop within floating tolerance
+    if start <= stop:
+        while x <= stop + 1e-9:
+            vals.append(x)
+            x += step
+    else:
+        while x >= stop - 1e-9:
+            vals.append(x)
+            x -= abs(step)
+    return vals

munchboka_edutools/_version.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.1.0"

munchboka_edutools/directives/__init__.py

@@ -0,0 +1 @@
+# Namespace package for directive modules. Each module should expose `setup(app)`.

munchboka_edutools/directives/admonitions.py

@@ -0,0 +1,356 @@
+"""
+Custom Admonition Directives
+=============================
+
+A collection of custom styled admonition directives for educational content.
+
+Directives included:
+- answer: For showing answers to problems (with dropdown option)
+- example: For worked examples
+- exercise: For exercise problems
+- explore: For exploratory activities
+- hints: For providing hints (with dropdown option)
+- solution: For full solutions (with dropdown option, default on)
+- summary: For chapter/section summaries
+- theory: For theoretical content
+
+All directives support MyST colon-fence syntax (:::).
+"""
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+
+
+class AnswerDirective(SphinxDirective):
+    """
+    Answer directive with optional dropdown.
+
+    Usage:
+        .. answer::
+        .. answer:: Custom Title
+        .. answer::
+            :dropdown: 0
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+
+    option_spec = {
+        "dropdown": directives.unchanged,
+    }
+
+    def run(self):
+        if len(self.arguments) > 0:
+            title = self.arguments[0]
+        else:
+            title = "Fasit"
+
+        # Create the admonition node
+        admonition_node = nodes.admonition()
+        admonition_node["classes"] = ["admonition", "answer"]
+
+        if "dropdown" in self.options:
+            dropdown_val = int(self.options["dropdown"])
+        else:
+            dropdown_val = 1
+
+        if dropdown_val == 1:
+            admonition_node["classes"].append("dropdown")
+
+        # Create the title node
+        title_node = nodes.title(text=title)
+        admonition_node += title_node
+
+        # Parse the content
+        self.state.nested_parse(self.content, self.content_offset, admonition_node)
+
+        return [admonition_node]
+
+
+class ExampleDirective(SphinxDirective):
+    """
+    Example directive for worked examples.
+
+    Usage:
+        .. example:: Example Title
+    """
+
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+
+    def run(self):
+        title = self.arguments[0]
+
+        # Create the admonition node
+        admonition_node = nodes.admonition()
+        admonition_node["classes"] = ["admonition", "example"]
+
+        # Create the title node
+        title_node = nodes.title()
+        parsed_title, _ = self.state.inline_text(title, self.lineno)
+        title_node += parsed_title
+        admonition_node += title_node
+
+        # Parse the content
+        self.state.nested_parse(self.content, self.content_offset, admonition_node)
+
+        return [admonition_node]
+
+
+class ExerciseDirective(SphinxDirective):
+    """
+    Exercise directive for problems.
+
+    Usage:
+        .. exercise:: Exercise Title
+        .. exercise:: Exercise Title
+            :level: 2
+    """
+
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {
+        "level": directives.unchanged,
+    }
+
+    def run(self):
+        title = self.arguments[0]
+        # Create the admonition node
+        admonition_node = nodes.admonition()
+        admonition_node["classes"] = ["admonition", "exercise"]
+
+        # Create the title node
+        title_node = nodes.title()
+        parsed_title, _ = self.state.inline_text(title, self.lineno)
+        title_node += parsed_title
+        admonition_node += title_node
+
+        # Parse the content
+        self.state.nested_parse(self.content, self.content_offset, admonition_node)
+
+        return [admonition_node]
+
+
+class ExploreDirective(SphinxDirective):
+    """
+    Explore directive for exploratory activities.
+
+    Usage:
+        .. explore:: Activity Title
+    """
+
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+
+    def run(self):
+        title = self.arguments[0]
+
+        # Create the admonition node
+        admonition_node = nodes.admonition()
+        admonition_node["classes"] = ["admonition", "explore"]
+
+        # Create the title node
+        title_node = nodes.title()
+        parsed_title, _ = self.state.inline_text(title, self.lineno)
+        title_node += parsed_title
+        admonition_node += title_node
+
+        # Parse the content
+        self.state.nested_parse(self.content, self.content_offset, admonition_node)
+
+        return [admonition_node]
+
+
+class HintsDirective(SphinxDirective):
+    """
+    Hints directive with optional dropdown.
+
+    Usage:
+        .. hints::
+        .. hints:: Custom Title
+        .. hints::
+            :dropdown: 0
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+
+    option_spec = {
+        "dropdown": directives.unchanged,
+    }
+
+    def run(self):
+        if len(self.arguments) > 0:
+            title = self.arguments[0]
+        else:
+            title = "Hint"
+
+        # Create the admonition node
+        admonition_node = nodes.admonition()
+        admonition_node["classes"] = ["admonition", "hints"]
+
+        if "dropdown" in self.options:
+            dropdown_val = int(self.options["dropdown"])
+        else:
+            dropdown_val = 1
+
+        if dropdown_val == 1:
+            admonition_node["classes"].append("dropdown")
+
+        # Create the title node
+        title_node = nodes.title(text=title)
+        admonition_node += title_node
+
+        # Parse the content
+        self.state.nested_parse(self.content, self.content_offset, admonition_node)
+
+        return [admonition_node]
+
+
+class SolutionDirective(SphinxDirective):
+    """
+    Solution directive with dropdown (default on).
+
+    Usage:
+        .. solution::
+        .. solution:: Custom Title
+        .. solution::
+            :dropdown: 0
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+
+    option_spec = {
+        "dropdown": directives.unchanged,
+    }
+
+    def run(self):
+        if len(self.arguments) > 0:
+            title = self.arguments[0]
+        else:
+            title = "Løsning"
+
+        # Create the admonition node
+        admonition_node = nodes.admonition()
+        admonition_node["classes"] = ["admonition", "solution"]
+
+        if self.options.get("dropdown"):
+            dropdown = self.options.get("dropdown")
+            if dropdown == "1":
+                admonition_node["classes"].append("dropdown")
+            elif dropdown == "0":
+                pass
+        else:
+            admonition_node["classes"].append("dropdown")
+
+        # Create the title node
+        title_node = nodes.title(text=title)
+        admonition_node += title_node
+
+        # Parse the content
+        self.state.nested_parse(self.content, self.content_offset, admonition_node)
+
+        return [admonition_node]
+
+
+class SummaryDirective(SphinxDirective):
+    """
+    Summary directive for chapter/section summaries.
+
+    Usage:
+        .. summary:: Summary Title
+    """
+
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+
+    def run(self):
+        title = self.arguments[0]
+
+        # Create the admonition node
+        admonition_node = nodes.admonition()
+        admonition_node["classes"] = ["admonition", "summary"]
+
+        title_node = nodes.title()
+        parsed_title, _ = self.state.inline_text(title, self.lineno)
+        title_node += parsed_title
+        admonition_node += title_node
+
+        # Parse the content
+        self.state.nested_parse(self.content, self.content_offset, admonition_node)
+
+        return [admonition_node]
+
+
+class TheoryDirective(SphinxDirective):
+    """
+    Theory directive for theoretical content.
+
+    Usage:
+        .. theory:: Theory Title
+    """
+
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+
+    def run(self):
+        title = self.arguments[0]
+
+        # Create the admonition node
+        admonition_node = nodes.admonition()
+        admonition_node["classes"] = ["admonition", "theory"]
+
+        # Create the title node
+        title_node = nodes.title()
+        parsed_title, _ = self.state.inline_text(title, self.lineno)
+        title_node += parsed_title
+        admonition_node += title_node
+
+        # Parse the content
+        self.state.nested_parse(self.content, self.content_offset, admonition_node)
+
+        return [admonition_node]
+
+
+def setup(app):
+    """
+    Setup all custom admonition directives.
+
+    Note: CSS files are registered in __init__.py with the munchboka/ prefix.
+    The admonitions.css file contains all styling for these directives.
+    """
+    app.add_directive("answer", AnswerDirective)
+    app.add_directive("example", ExampleDirective)
+    app.add_directive("exercise", ExerciseDirective)
+    app.add_directive("explore", ExploreDirective)
+    app.add_directive("hints", HintsDirective)
+    app.add_directive("solution", SolutionDirective)
+    app.add_directive("summary", SummaryDirective)
+    app.add_directive("theory", TheoryDirective)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }