Merge pull request #289 from machow/fix-section-transform

fix: ensure docstring section transform preserves starting text

quartodoc/ast.py

@@ -76,6 +76,11 @@ def split_sections(text) -> list[tuple[str, str]]:
         # in order to find the body of text between multiple sections.
         results = []
         while crnt_match is not None:
+            # if the first section comes later in the text, ensure that we
+            # create a section for the very beginning
+            if crnt_pos == 0 and crnt_match.start() > 0:
+                results.append(("", text[: crnt_match.start()]))
+
             next_pos = crnt_pos + crnt_match.end()
             substr = text[next_pos:]
             next_match = comp.search(substr)

quartodoc/tests/test_ast.py

@@ -14,7 +14,6 @@
         ("See Also\n---", ""),
         ("See Also\n---\n", ""),
         ("See Also\n--------", ""),
-        ("\n\nSee Also\n---\n", ""),
         ("See Also\n---\nbody text", "body text"),
         ("See Also\n---\nbody text", "body text"),
     ],
@@ -29,6 +28,19 @@ def test_transform_docstring_section(el, body):
     assert res[0].value == body
 
 
+def test_transform_docstring_section_multiple():
+    # Note the starting text is not a section header
+    # so this should be split into two sections: short description, and see also.
+    src = ds.DocstringSectionText("A short description\n\nSee Also\n---\n")
+    res = qast._DocstringSectionPatched.transform(src)
+
+    assert len(res) == 2
+    assert res[0].value == "A short description\n\n"
+    assert isinstance(res[1], qast.DocstringSectionSeeAlso)
+    assert res[1].title == "See Also"
+    assert res[1].value == ""
+
+
 @pytest.mark.parametrize(
     "el, cls",
     [