Merge pull request #367 from machow/fix-anchors-strip

Fix: make header css classes more robust by stripping non-alphanumerics

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,10 +292,11 @@ def render_header(self, el: layout.Doc) -> str:
 
     @dispatch
     def render_header(self, el: ds.DocstringSection) -> str:
-        title = el.title or el.kind.value
-        _classes = [".doc-section", ".doc-section-" + title.replace(" ", "-")]
+        title = el.title or el.kind.value.title()
+        anchor_part = _sanitize_title(title.lower())
+        _classes = [".doc-section", f".doc-section-{anchor_part}"]
         _str_classes = " ".join(_classes)
-        return f"{'#' * self.crnt_header_level} {title.title()} {{{_str_classes}}}"
+        return f"{'#' * self.crnt_header_level} {title} {{{_str_classes}}}"
 
     # render method -----------------------------------------------------------
 

quartodoc/tests/__snapshots__/test_renderers.ambr

@@ -398,7 +398,7 @@
   | a      | int    | The a parameter. | _required_ |
   | b      | str    | The b parameter. | _required_ |
 
-  ## Custom Admonition {.doc-section .doc-section-Custom-Admonition}
+  ## Custom Admonition {.doc-section .doc-section-custom-admonition}
 
   Some text.
   '''
@@ -420,7 +420,7 @@
   | a      |        | The a parameter. | _required_ |
   | b      | str    | The b parameter. | _required_ |
 
-  ## Custom Admonition {.doc-section .doc-section-Custom-Admonition}
+  ## Custom Admonition {.doc-section .doc-section-custom-admonition}
 
   Some text.
   '''

quartodoc/tests/test_renderers.py

@@ -18,6 +18,9 @@ def renderer():
     return MdRenderer()
 
 
+# Smaller parts ----------------------------------------------------------------
+
+
 def test_render_param_kwargs(renderer):
     f = get_object("quartodoc.tests.example_signature.no_annotations")
     res = renderer.render(f.parameters)
@@ -126,6 +129,18 @@ def test_render_doc_section_admonition(renderer):
     assert res == "quartodoc.tests.example: Method for doing a thing"
 
 
+def test_render_doc_section_header_anchor(renderer):
+    section = ds.DocstringSection(title="a `chaotic` {.title}")
+
+    dst = "# a `chaotic` {.title} {.doc-section .doc-section-a-chaotic-title}"
+
+    assert renderer.render_header(section) == dst
+
+
+# Big pieces -------------------------------------------------------------------
+# These are mostly snapshots
+
+
 @pytest.mark.parametrize("children", ["embedded", "flat", "linked"])
 def test_render_doc_module(snapshot, renderer, children):
     bp = blueprint(Auto(name="quartodoc.tests.example", children=children))