markdown: Fix graphicspath bug

Pattern matching was too rigid, replace with regex expression.

Also make `markdown` non-private so it appears in API docs.

Author: harens

docs/source/filters.py

@@ -22,7 +22,7 @@ def generate_filters_docs():
     filters = (
         i.name
         for i in pkgutil.iter_modules(in2lambda.filters.__path__)
-        if i.name[0] != "_"
+        if i.name != "markdown"
     )
 
     for filter_name in filters:

in2lambda/filters/PartPartSolSol/filter.py

@@ -7,7 +7,7 @@
 import panflute as pf
 
 from in2lambda.api.module import Module
-from in2lambda.filters._markdown import filter
+from in2lambda.filters.markdown import filter
 
 
 @filter

in2lambda/filters/PartSolPartSol/filter.py

@@ -8,7 +8,7 @@
 import panflute as pf
 
 from in2lambda.api.module import Module
-from in2lambda.filters._markdown import filter
+from in2lambda.filters.markdown import filter
 
 
 @filter

in2lambda/filters/PartsOneSol/filter.py

@@ -10,7 +10,7 @@
 import panflute as pf
 
 from in2lambda.api.module import Module
-from in2lambda.filters._markdown import filter
+from in2lambda.filters.markdown import filter
 
 
 @filter

in2lambda/filters/PartsSepSol/filter.py

@@ -10,7 +10,7 @@
 import panflute as pf
 
 from in2lambda.api.module import Module
-from in2lambda.filters._markdown import filter
+from in2lambda.filters.markdown import filter
 
 
 @filter

in2lambda/filters/_markdown.py in2lambda/filters/markdown.pyin2lambda/filters/_markdown.py renamed to in2lambda/filters/markdown.py

@@ -1,5 +1,7 @@
 """Generic helper functions used during the Pandoc filter stage for markdown conversion."""
 
+import os
+import re
 from functools import cache
 from pathlib import Path
 
@@ -13,60 +15,103 @@
 
 @cache
 def image_directories(tex_file: str) -> list[str]:
-    """Determines the image directories referenced by `graphicspath` in a given TeX document.
+    r"""Determines the image directories referenced by `graphicspath` in a given TeX document.
 
     Args:
         tex_file: The absolute path to a TeX file
 
     Returns:
         The exact contents of `graphicspath`, regardless of whether the directories are
         absolute or relative.
+
+    Examples:
+        >>> from in2lambda.filters.markdown import image_directories
+        >>> import tempfile
+        >>> import os
+        >>> # Example TeX file with a graphicspath
+        >>> temp_dir = tempfile.mkdtemp()
+        >>> tex_file = os.path.join(temp_dir, 'test.tex')
+        >>> with open(tex_file, 'w') as f:
+        ...     f.write("\graphicspath{{subdir1/}{subdir2/}{subdir3/}}")
+        45
+        >>> image_directories(tex_file)
+        ['subdir1/', 'subdir2/', 'subdir3/']
+        >>> with open(tex_file, 'w') as f:
+        ...    f.write("\graphicspath{ { subdir1/ }, { subdir2/ }, { subdir3/ } }")
+        57
+        >>> image_directories.cache_clear()
+        >>> image_directories(tex_file)
+        ['subdir1/', 'subdir2/', 'subdir3/']
+        >>> with open(tex_file, 'w') as f:
+        ...    f.write("No image directory")
+        18
+        >>> image_directories.cache_clear()
+        >>> image_directories(tex_file)
+        []
     """
     with open(tex_file, "r") as file:
         for line in file:
-            # Assumes line is in the format \graphicspath{ {...}, {...}, ...}
             if "graphicspath" in line:
-                return [
-                    i.strip("{").rstrip("}")
-                    for i in line.replace(" ", "")[len("\graphicspath{") : -1].split(
-                        ","
-                    )
-                ]
+                # Matches anything surrounded by curly braces, but excludes the top level
+                # graphicspath brace.
+                return [match.strip() for match in re.findall(r"{([^{]*?)}", line)]
     return []
 
 
+# TODO: This assumes the file extension is included, but that isn't required by LaTeX
+# See: https://www.overleaf.com/learn/latex/Inserting_Images#Generating_high-res_and_low-res_images
 def image_path(image_name: str, tex_file: str) -> Optional[str]:
-    """Determines the absolute path to an image referenced in a tex_file.
+    r"""Determines the absolute path to an image referenced in a tex_file.
 
     Args:
         image_name: The file name of the image e.g. example.png
         tex_file: The TeX file that references the image.
 
     Returns:
         The absolute path to the image if it can be found. If not, it returns None.
+
+    Examples:
+        >>> from in2lambda.filters.markdown import image_path
+        >>> import tempfile
+        >>> import os
+        >>> # Example TeX file with a subdirectory
+        >>> temp_dir = tempfile.mkdtemp()
+        >>> tex_file = os.path.join(temp_dir, 'test.tex')
+        >>> with open(tex_file, 'w') as f:
+        ...     f.write("\graphicspath{{./subdir1/}{./subdir2/}{./subdir3/}}")
+        51
+        >>> # Example image in a relative subdirectory
+        >>> sub_dir = os.path.join(temp_dir, 'subdir3')
+        >>> os.makedirs(sub_dir)
+        >>> with open(os.path.join(sub_dir, 'inside_folder.png'), 'w') as f:
+        ...     pass
+        >>> image_path("inside_folder.png", tex_file) == os.path.join(temp_dir, 'subdir3', "inside_folder.png")
+        True
+        >>> # Absolute path provided
+        >>> image_path(os.path.join(temp_dir, 'subdir3', "inside_folder.png"), tex_file) == os.path.join(temp_dir, 'subdir3', "inside_folder.png")
+        True
     """
     # In case the filename is the exact absolute/relative location to the image
     # When handling relative locations (i.e. begins with dot), first go to the directory of the TeX file.
-    filename = (
-        f"{str(Path(tex_file).parent)}/" if image_name[0] == "." else ""
-    ) + image_name
+
+    filename = os.path.join(
+        str(Path(tex_file).parent) if image_name[0] == "." else "", image_name
+    )
 
     if Path(filename).is_file():
-        return filename
+        return os.path.normpath(filename)
 
     # Absolute or relative directories referenced by `graphicspath`
     image_locations = image_directories(tex_file)
 
     for directory in image_locations:
-        if directory[-1] != "/":
-            directory += "/"
-        filename = (
-            (f"{str(Path(tex_file).parent)}/" if directory[0] == "." else "")
-            + directory
-            + image_name
+        filename = os.path.join(
+            str(Path(tex_file).parent) if directory[0] == "." else "",
+            directory,
+            image_name,
         )
         if Path(filename).is_file():
-            return filename
+            return os.path.normpath(filename)
     return None
 
 

in2lambda/katex_convert/katex_convert.py

@@ -34,6 +34,9 @@ def latex_to_katex(latex_string: str) -> str:
 
     Returns:
         Hopefully, a valid KaTeX expression that's similar to the LaTeX expression.
+
+    Examples:
+        >>>
     """
     katex_string = replace_functions(delete_functions(latex_string))
     return katex_string
@@ -143,7 +146,7 @@ def brace_remover(latex_string: str, brace_start_index: int) -> str:
 
 
 if __name__ == "__main__":
-    latex_input = """ \\textbf{Vector Algebra:} for two vectors $\\vec{a}$ and $\\vec{b}$ in $\\mathbb{R}^3$ given by \\norm{a}"""
+    latex_input = "\\textbf{Vector Algebra:} for two vectors $\\vec{a}$ and $\\vec{b}$ in $\\mathbb{R}^3$ given by \\norm{a}"
 
     katex_output = latex_to_katex(latex_input)
     print(katex_output)

in2lambda/main.py

@@ -130,7 +130,7 @@ def runner(
         [
             i.name
             for i in pkgutil.iter_modules(in2lambda.filters.__path__)
-            if i.name[0] != "_"
+            if i.name != "markdown"
         ],
         case_sensitive=False,
     ),