fix: sanitize css class names in headers; use doctest

Author: machow

pyproject.toml

@@ -9,7 +9,7 @@ include = ["quartodoc"]
 
 [tool.pytest.ini_options]
 markers = []
-testpaths = ["quartodoc/tests"]
+testpaths = ["quartodoc"]
 
 [project]
 name = "quartodoc"

quartodoc/ast.py

@@ -375,10 +375,10 @@ def preview(
     >>> obj = get_object("quartodoc", "get_object")
 
     >>> preview(obj.docstring.parsed)
-     ...
+    ...
 
     >>> preview(obj)
-     ...
+    ...
 
     """
 

quartodoc/renderers/md_renderer.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import black
+import re
 import quartodoc.ast as qast
 
 from contextlib import contextmanager
@@ -26,6 +27,28 @@ def _has_attr_section(el: dc.Docstring | None):
     return any([isinstance(x, ds.DocstringSectionAttributes) for x in el.parsed])
 
 
+def _sanitize_title(title: str):
+    """Replace characters so that title can be used as an anchor, by
+
+    Approach:
+       * replace spaces with -, then
+       * stripping non alphanumeric characters
+
+    Examples
+    --------
+
+    >>> _sanitize_title("a b c")
+    'a-b-c'
+    >>> _sanitize_title("a b! c")
+    'a-b-c'
+    >>> _sanitize_title("a`b`c{")
+    'abc'
+
+    """
+
+    return re.sub(r"[^a-zA-Z0-9-]+", "", title.replace(" ", "-"))
+
+
 @dataclass
 class ParamRow:
     name: str | None
@@ -269,7 +292,7 @@ def render_header(self, el: layout.Doc) -> str:
 
     @dispatch
     def render_header(self, el: ds.DocstringSection) -> str:
-        title = el.title or el.kind.value
+        title = _sanitize_title(el.title or el.kind.value)
         _classes = [".doc-section", ".doc-section-" + title.replace(" ", "-")]
         _str_classes = " ".join(_classes)
         return f"{'#' * self.crnt_header_level} {title.title()} {{{_str_classes}}}"