Merge remote-tracking branch 'origin/markdown-filter' into cli-group

Author: m-messer

in2lambda/filters/Markdown/example.md

@@ -5,7 +5,10 @@ $v_0 = 15\,\text{m/s}$. Take $g = 9.8\,\text{m/s}^2$.
 
 ## Time of flight
 
-How long does the ball take to reach the ground?
+How long does the ball take to reach the ground, using:
+
+- the vertical motion equation
+- the given height and gravity
 
 ## Solution
 
@@ -15,6 +18,8 @@ $$
 h = \frac{1}{2} g t^2 \implies t = \sqrt{\frac{2h}{g}}
 $$
 
+---
+
 So $t \approx 2.0\,\text{s}$.
 
 ## Horizontal range

in2lambda/filters/Markdown/filter.py

@@ -68,7 +68,7 @@ def pandoc_filter(
     doc: pf.elements.Doc,
     set: Set,
     parsing_answers: bool,
-) -> Optional[pf.Str]:
+) -> Optional[pf.Inline]:
     """Turn a ``#``/``##`` markdown document into questions, parts and solutions.
 
     Args:
@@ -87,12 +87,27 @@ def pandoc_filter(
 
     state = _state_for(doc)
     is_heading = isinstance(elem, pf.Header)
-    text = pf.stringify(elem).strip()
+    is_rule = isinstance(elem, pf.HorizontalRule)
+
+    if is_heading:
+        text = pf.stringify(elem).strip()
+    elif is_rule:
+        # HorizontalRule blocks (``---``) stringify to nothing, so they're matched
+        # separately and kept as literal text: in a Lambda Feedback worked solution
+        # they mark the boundary between the steps a student clicks through.
+        text = "---"
+    else:
+        # Serialized back to markdown (rather than flattened with pf.stringify) so
+        # that lists, tables and other markup survive into the question/part/
+        # solution text verbatim.
+        text = pf.convert_text(
+            elem, input_format="panflute", output_format="markdown"
+        ).strip()
 
     if parsing_answers:
         if is_heading and elem.level == 1:
             set.increment_current_question()
-        elif not is_heading and text:
+        elif (is_rule or not is_heading) and text:
             set.current_question.add_solution(text)
         return None
 
@@ -108,7 +123,7 @@ def pandoc_filter(
         state.part = Part()
         set.current_question.parts.append(state.part)
         state.target = "part"
-    elif not is_heading and text:
+    elif (is_rule or not is_heading) and text:
         if state.target == "main":
             set.current_question.main_text = text
         elif state.target == "part" and state.part is not None:

in2lambda/filters/markdown.py

@@ -118,11 +118,11 @@ def image_path(image_name: str, tex_file: str) -> Optional[str]:
 def filter(
     func: Callable[
         [pf.Element, pf.elements.Doc, Set, bool],
-        Optional[pf.Str],
+        Optional[pf.Inline],
     ]
 ) -> Callable[
     [pf.Element, pf.elements.Doc, Set, str, bool],
-    Optional[pf.Str],
+    Optional[pf.Inline],
 ]:
     """Python decorator to make generic LaTeX elements markdown readable.
 
@@ -139,7 +139,7 @@ def markdown_converter(
         set: Set,
         tex_file: str,
         parsing_answers: bool,
-    ) -> Optional[pf.Str]:
+    ) -> Optional[pf.Inline]:
         """Handles LaTeX elements within the filter, before calling the original function.
 
         N.B. tex_file is required to determine where the relative image directory is.
@@ -163,10 +163,13 @@ def markdown_converter(
                     expression = latex_to_katex(elem.text)
                 except Exception:
                     expression = elem.text
-                return pf.Str(
-                    f"${expression}$"
-                    if elem.format == "InlineMath"
-                    else f"\n\n$$\n{expression}\n$$\n\n"
+                return pf.RawInline(
+                    (
+                        f"${expression}$"
+                        if elem.format == "InlineMath"
+                        else f"\n\n$$\n{expression}\n$$\n\n"
+                    ),
+                    format="markdown",
                 )
 
             case pf.Image:
@@ -176,13 +179,13 @@ def markdown_converter(
                     echo(f"Warning: Couldn't find {elem.url}")
                 else:
                     set.current_question.images.append(path)
-                return pf.Str(f"![pictureTag]({elem.url})")
+                return pf.RawInline(f"![pictureTag]({elem.url})", format="markdown")
 
             case pf.Strong:
-                return pf.Str(f"**{pf.stringify(elem)}**")
+                return pf.RawInline(f"**{pf.stringify(elem)}**", format="markdown")
 
             case pf.Emph:
-                return pf.Str(f"*{pf.stringify(elem)}*")
+                return pf.RawInline(f"*{pf.stringify(elem)}*", format="markdown")
 
             # Replace siunitx no-break space with narrow no-break space
             # This should be the space between the number and the units

in2lambda/main.py

@@ -22,7 +22,7 @@
 def _warn_markdown_issues(text: str, source: str) -> None:
     """Echo a warning for each math-delimiter problem found in a markdown source."""
     for problem in check_markdown(text):
-        click.echo(f"Warning: {source}: {problem.value}")
+        click.echo(f"Warning: {source}: {problem}")
 
 
 def docx_to_md(docx_file: str) -> str:

in2lambda/validation/__init__.py

@@ -6,32 +6,35 @@
 delimiters - before the markdown is converted.
 """
 
-from in2lambda.validation.delimiters import MathDelimiterError, math_delimiter_checker
+from in2lambda.validation.delimiters import (
+    MathDelimiterError,
+    MathDelimiterProblem,
+    math_delimiter_checker,
+)
 
-__all__ = ["MathDelimiterError", "math_delimiter_checker", "check_markdown"]
+__all__ = [
+    "MathDelimiterError",
+    "MathDelimiterProblem",
+    "math_delimiter_checker",
+    "check_markdown",
+]
 
 
-def check_markdown(md_content: str) -> list[MathDelimiterError]:
+def check_markdown(md_content: str) -> list[MathDelimiterProblem]:
     """Run every markdown check and return the problems found.
 
     Args:
         md_content: The markdown text to validate.
 
     Returns:
-        A list of :class:`MathDelimiterError` members, one per problem found.
+        A list of :class:`MathDelimiterProblem`, one per problem found.
         An empty list means the markdown passed every check.
 
     Examples:
         >>> from in2lambda.validation import check_markdown
         >>> check_markdown("Inline $x = y$ is fine.")
         []
         >>> check_markdown("Unbalanced $x = y")
-        [<MathDelimiterError.MISSING_CLOSING_SINGLE_DOLLAR: 'unclosed inline $ ... $'>]
+        [MathDelimiterProblem(line=1, error=<MathDelimiterError.MISSING_CLOSING_SINGLE_DOLLAR: 'unclosed inline $ ... $'>)]
     """
-    problems: list[MathDelimiterError] = []
-
-    result = math_delimiter_checker(md_content)
-    if result is not MathDelimiterError.PASSED:
-        problems.append(result)
-
-    return problems
+    return math_delimiter_checker(md_content)