munchboka-edutools 0.2.3__py3-none-any.whl

munchboka_edutools/directives/escape_room.py

@@ -0,0 +1,296 @@
+"""
+Escape Room Directive
+=====================
+
+A Sphinx directive for creating interactive escape room puzzles where students must
+solve problems sequentially by entering codes to unlock the next room.
+
+Usage:
+    .. escape-room::
+        :case_insensitive:
+
+        Puzzle: Step 1 title
+        Code: ABC123
+        Q: Question text can include markdown images and code
+           ![{width="60%" class="adaptive-figure"}](path/to/img.png)
+
+        Puzzle: Step 2 title
+        Code: 42, forty-two, XLII
+        Q: More content ...
+
+Recognized headers (case-insensitive):
+  - Puzzle: or Step:  - Starts a new puzzle/room
+  - Code:             - Code(s) to unlock this room (comma-separated for multiple)
+  - Q:                - Question/content for this room
+
+MyST Syntax (colon-fence):
+    :::{escaperoom}
+    :case_insensitive:
+
+    Puzzle: Step 1 title
+    Code: ABC123
+    Q: Question text
+    :::
+
+Note: Due to MyST limitations with hyphens in directive names when using colon-fence
+syntax (:::), the directive is also registered as "escaperoom" (no hyphen).
+"""
+
+from __future__ import annotations
+
+import json
+import html as _html
+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 EscapeRoomDirective(SphinxDirective):
+    """Directive that renders an Escape-Room style sequence of puzzles.
+
+    Only one question is shown at a time; students must type a code to unlock
+    the next. Supports figures and code blocks like quiz/jeopardy.
+    """
+
+    has_content = True
+    required_arguments = 0
+    option_spec = {
+        # Placeholder for future options (e.g., case-insensitive codes)
+        "case_insensitive": directives.flag,
+    }
+
+    def run(self):
+        self.board_id = uuid.uuid4().hex
+        container_id = f"escape-room-{self.board_id}"
+
+        data = self._parse_content()
+
+        # Compute relative prefix to _static (same approach as jeopardy)
+        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)
+
+        json_str = json.dumps(data, ensure_ascii=False)
+        # Escape JSON for safe embedding in a double-quoted attribute
+        attr_json = _html.escape(json_str, quote=True)
+
+        # Note: CSS and JS are registered in __init__.py with munchboka/ prefix
+        # KaTeX is also loaded globally, no need to load it per-directive
+        html = f"""
+        <div id="{container_id}" class="escape-room-container" data-config="{attr_json}">
+          <script type="application/json" class="escape-room-data">{json_str}</script>
+        </div>
+        """
+
+        return [nodes.raw("", html, format="html")]
+
+    # -------------------- parsing helpers --------------------
+    def _parse_content(self) -> Dict[str, Any]:
+        steps: List[Dict[str, Any]] = []
+        current: Dict[str, Any] | None = None
+        current_section: str | None = None  # 'Q'
+
+        def flush():
+            nonlocal current
+            if current is not None:
+                # normalize
+                current.setdefault("title", "")
+                codes = current.get("codes") or []
+                current["codes"] = [str(c).strip() for c in codes if str(c).strip()]
+                current.setdefault("question", "")
+                # post-process code blocks
+                current["question"] = self._process_code_blocks(current["question"])
+                steps.append(current)
+            current = None
+
+        for raw in self.content:
+            line = self._process_figures(raw) or raw
+            s = line.rstrip("\n")
+
+            # Puzzle/Step header
+            m = re.match(r"^\s*(?:Puzzle|Step)\s*:\s*(.+?)\s*$", s, flags=re.IGNORECASE)
+            if m:
+                flush()
+                current = {"title": m.group(1).strip(), "codes": [], "question": ""}
+                current_section = None
+                continue
+
+            # Code line (allow comma-separated)
+            m = re.match(r"^\s*Code\s*:\s*(.+?)\s*$", s, flags=re.IGNORECASE)
+            if m and current is not None:
+                codes_str = m.group(1).strip()
+                codes = [c.strip() for c in re.split(r",|;", codes_str)] if codes_str else []
+                current["codes"] = codes
+                continue
+
+            # Q: starts question block
+            m = re.match(r"^\s*Q\s*:\s*(.*)$", s, flags=re.IGNORECASE)
+            if m and current is not None:
+                current_section = "Q"
+                current["question"] = (current.get("question") or "") + m.group(1)
+                continue
+
+            # Continuation
+            if current_section == "Q" and current is not None:
+                current["question"] = (current.get("question") or "") + "\n" + s
+                continue
+
+        flush()
+
+        case_insensitive = "case_insensitive" in self.options
+        return {"steps": steps, "caseInsensitive": bool(case_insensitive)}
+
+    def _process_figures(self, text):
+        """Copy images to _static/figurer/... and rewrite to HTML, like quiz/jeopardy."""
+        import shutil
+        import json as _json
+
+        if not hasattr(self, "_image_counter"):
+            self._image_counter = 0
+
+        def _parse_figure_options(alt_text):
+            # Support JSON-like {width: 60%, class: adaptive-figure} and key=value forms
+            opts = {}
+            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 _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
+
+        def _build_figure_html(html_img_path, options):
+            user_opts = dict(options or {})
+            user_class = user_opts.pop("class", "").strip()
+            classes = "escape-room-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)
+
+            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:
+                attrs.append(f'style="{' '.join(styles)}"')
+            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="escape-room-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="escape-room-image adaptive-figure" alt="Figure (missing)">'  # noqa: E501
+
+            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:
+        """Process HTML code blocks to handle escaped newlines (like quiz)."""
+
+        def replace_newlines(match):
+            lang = match.group(1)
+            code = match.group(2)
+            code = code.replace("\\n", "\n")
+            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):
+    """
+    Setup the escape-room directive.
+
+    Registers the directive under two names:
+    - "escape-room" for RST compatibility
+    - "escaperoom" for MyST colon-fence compatibility (no hyphens allowed)
+
+    Note: CSS and JS files are registered in __init__.py with the munchboka/ prefix
+    """
+    app.add_directive("escape-room", EscapeRoomDirective)
+    app.add_directive("escaperoom", EscapeRoomDirective)  # MyST compatibility
+
+    return {"version": "0.1", "parallel_read_safe": True, "parallel_write_safe": True}

munchboka_edutools/directives/escape_room2.py

@@ -0,0 +1,318 @@
+"""
+Escape Room 2.0 Directive System
+=================================
+
+A modular escape room system using nested directives:
+- escape-room-2: Main container
+- room: Individual room/puzzle with nested content support
+
+Features:
+- Supports nested directives (plot, code, cas-popup, etc.) in rooms
+- Markdown/MyST formatting support
+- Math rendering with KaTeX
+- Preserves existing escape-room JavaScript functionality
+
+Usage:
+-----
+::::::{escape-room-2}
+
+::::{room}
+---
+code: 144
+---
+What is 12 × 12?
+
+:::{plot}
+:function: x**2
+:::
+::::
+
+::::{room}
+---
+code: abc123
+---
+Next puzzle...
+::::
+
+::::::
+"""
+
+from docutils import nodes
+from docutils.statemachine import StringList
+from sphinx.util.docutils import SphinxDirective
+from docutils.parsers.rst import directives
+import json
+import uuid
+import html as _html
+
+
+class EscapeRoom2Directive(SphinxDirective):
+    """Main container directive for Escape Room 2.0.
+
+    Collects nested room directives and generates the escape room HTML.
+    """
+
+    has_content = True
+    required_arguments = 0
+    option_spec = {
+        "case_insensitive": directives.flag,
+    }
+
+    def run(self):
+        # Generate unique ID for this escape room
+        self.board_id = f"escape-room-{uuid.uuid4().hex[:8]}"
+
+        # Store escape room ID in environment for nested directives
+        if not hasattr(self.env, "temp"):
+            self.env.temp = {}
+
+        self.env.temp["current_escaperoom2_id"] = self.board_id
+
+        # Parse nested content (room directives)
+        container = nodes.container()
+        self.state.nested_parse(self.content, self.content_offset, container)
+
+        # Get rooms from environment
+        rooms_key = f"escaperoom2_rooms_{self.board_id}"
+        rooms = self.env.temp.get(rooms_key, [])
+
+        # Generate HTML output
+        container_id = f"escape-room-{self.board_id}"
+        case_insensitive = "case_insensitive" in self.options
+        html = self._generate_escape_room_html(container_id, rooms, case_insensitive)
+
+        # Clean up environment
+        self.env.temp.pop(rooms_key, None)
+        if "current_escaperoom2_id" in self.env.temp:
+            self.env.temp.pop("current_escaperoom2_id")
+
+        return [nodes.raw("", html, format="html")]
+
+    def _generate_escape_room_html(
+        self, container_id: str, rooms: list, case_insensitive: bool
+    ) -> str:
+        """Generate the HTML for the escape room."""
+        data = {"steps": rooms, "caseInsensitive": case_insensitive}
+
+        # Escape </script> and </style> tags to prevent breaking the JSON script tag
+        json_str = json.dumps(data, ensure_ascii=False)
+        json_str = json_str.replace("</script>", "<\\/script>").replace("</style>", "<\\/style>")
+
+        # Escape JSON for safe embedding in a double-quoted attribute
+        attr_json = _html.escape(json_str, quote=True)
+
+        html = f"""
+        <div id="{container_id}" class="escape-room-container" data-config="{attr_json}">
+          <script type="application/json" class="escape-room-data">{json_str}</script>
+        </div>
+        """
+
+        return html
+
+
+class RoomDirective(SphinxDirective):
+    """Individual room directive for Escape Room 2.0.
+
+    Accepts front matter (code, title) and content that can include any other directives.
+    """
+
+    has_content = True
+    required_arguments = 0
+    option_spec = {
+        "code": directives.unchanged_required,
+        "title": directives.unchanged,
+    }
+
+    def run(self):
+        # Get the current escape room ID from the environment
+        if not hasattr(self.env, "temp"):
+            self.env.temp = {}
+
+        escaperoom_id = self.env.temp.get("current_escaperoom2_id")
+        if escaperoom_id is None:
+            error_msg = self.state_machine.reporter.error(
+                "room directive must be used inside an escape-room-2 directive",
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno,
+            )
+            return [error_msg]
+
+        # Parse front matter and content
+        code, title, content_lines = self._parse_content()
+
+        # Use options if provided, otherwise use front matter
+        code = self.options.get("code", code)
+        title = self.options.get("title", title or "")
+
+        if not code:
+            error_msg = self.state_machine.reporter.error(
+                "room directive requires a 'code' (either in front matter or as option)",
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno,
+            )
+            return [error_msg]
+
+        # Parse codes (can be comma/semicolon separated)
+        import re
+
+        codes = [c.strip() for c in re.split(r"[,;]", code)] if code else []
+
+        # Render content to HTML
+        question_html = self._render_to_html(content_lines)
+
+        # Store room in environment
+        rooms_key = f"escaperoom2_rooms_{escaperoom_id}"
+        if rooms_key not in self.env.temp:
+            self.env.temp[rooms_key] = []
+
+        self.env.temp[rooms_key].append({"title": title, "codes": codes, "question": question_html})
+
+        # Return empty list - the parent escape-room-2 directive will render everything
+        return []
+
+    def _parse_content(self):
+        """Parse front matter and content from the directive body."""
+        code = None
+        title = None
+        content_start = 0
+
+        # Check for YAML front matter (---)
+        if len(self.content) > 0 and self.content[0].strip() == "---":
+            # Find the closing ---
+            end_idx = None
+            for i in range(1, len(self.content)):
+                if self.content[i].strip() == "---":
+                    end_idx = i
+                    break
+
+            if end_idx is not None:
+                # Parse front matter
+                for i in range(1, end_idx):
+                    line = self.content[i].strip()
+                    if ":" in line:
+                        key, value = line.split(":", 1)
+                        key = key.strip().lower()
+                        value = value.strip()
+
+                        if key == "code":
+                            code = value
+                        elif key == "title":
+                            title = value
+
+                content_start = end_idx + 1
+
+        # Get content lines after front matter
+        content_lines = self.content[content_start:] if content_start < len(self.content) else []
+
+        return code, title, content_lines
+
+    def _render_to_html(self, content_lines: StringList) -> str:
+        """Render content lines to HTML, processing any nested directives."""
+        if not content_lines:
+            return ""
+
+        # Create a container node for the content
+        container = nodes.container()
+
+        # Parse the content, which will process nested directives
+        self.state.nested_parse(content_lines, self.content_offset, container)
+
+        # Convert to HTML
+        html_parts = []
+        for node in container.children:
+            html_parts.append(self._node_to_html(node))
+
+        return "\n".join(html_parts)
+
+    def _node_to_html(self, node) -> str:
+        """Convert a docutils node to HTML string."""
+        if isinstance(node, nodes.paragraph):
+            content = "".join(self._node_to_html(child) for child in node.children)
+            return f"<p>{content}</p>"
+
+        elif isinstance(node, nodes.Text):
+            return _html.escape(str(node))
+
+        elif isinstance(node, nodes.raw):
+            if node.get("format") == "html":
+                return node.astext()
+            return ""
+
+        elif isinstance(node, nodes.math):
+            # Render inline math using KaTeX-compatible format
+            math_text = node.astext()
+            return f"${math_text}$"
+
+        elif isinstance(node, nodes.math_block):
+            # Render display math ($$...$$) using KaTeX-compatible format
+            math_text = node.astext()
+            return f"$${math_text}$$"
+
+        elif isinstance(node, nodes.image):
+            uri = node.get("uri", "")
+            alt = node.get("alt", "")
+            return f'<img src="{uri}" alt="{alt}" />'
+
+        elif isinstance(node, nodes.literal_block):
+            content = _html.escape(node.astext())
+            language = node.get("language", "")
+            return f'<pre><code class="{language}">{content}</code></pre>'
+
+        elif isinstance(node, nodes.figure):
+            # Handle figure nodes (e.g., from plot directive)
+            content = "".join(self._node_to_html(child) for child in node.children)
+            classes = " ".join(node.get("classes", []))
+            align = node.get("align", "center")
+
+            attrs = []
+            if classes:
+                attrs.append(f'class="{classes}"')
+            if align:
+                attrs.append(f'align="{align}"')
+
+            attrs_str = " ".join(attrs) if attrs else ""
+            return f"<figure {attrs_str}>{content}</figure>"
+
+        elif isinstance(node, nodes.caption):
+            content = "".join(self._node_to_html(child) for child in node.children)
+            return f"<figcaption>{content}</figcaption>"
+
+        elif isinstance(node, nodes.bullet_list):
+            content = "".join(self._node_to_html(child) for child in node.children)
+            return f"<ul>{content}</ul>"
+
+        elif isinstance(node, nodes.enumerated_list):
+            content = "".join(self._node_to_html(child) for child in node.children)
+            return f"<ol>{content}</ol>"
+
+        elif isinstance(node, nodes.list_item):
+            content = "".join(self._node_to_html(child) for child in node.children)
+            return f"<li>{content}</li>"
+
+        elif isinstance(node, nodes.container):
+            content = "".join(self._node_to_html(child) for child in node.children)
+            classes = " ".join(node.get("classes", []))
+            if classes:
+                return f'<div class="{classes}">{content}</div>'
+            return content
+
+        elif hasattr(node, "children"):
+            return "".join(self._node_to_html(child) for child in node.children)
+
+        else:
+            return ""
+
+
+def setup(app):
+    """Register the directives with Sphinx."""
+    app.add_directive("escape-room-2", EscapeRoom2Directive)
+    app.add_directive("room", RoomDirective)
+
+    # Reuse the same CSS/JS as original escape-room
+    try:
+        app.add_css_file("munchboka/css/escapeRoom/escape-room.css")
+        app.add_js_file("munchboka/js/escapeRoom/escape-room.js")
+    except Exception:
+        pass
+
+    return {"version": "0.2", "parallel_read_safe": True, "parallel_write_safe": True}