simply management of docstring sections

Author: jalvesz

src/sphinx_fortran_domain/directives.py

@@ -86,50 +86,33 @@ def _read_program_source_by_search(env, progname: str, *, doc_markers: list[str]
 	return (None, None)
 
 
-def _split_out_examples_sections(text: str | None) -> tuple[str | None, str | None]:
-	"""Split docstring into (main, examples) where examples are '## Example(s)' sections.
+def _split_out_doc_section_blocks(text: str | None) -> tuple[str | None, str | None]:
+	"""Split a docstring into (preamble, sections) based on our "## Title" markers.
 
-	We treat sections introduced by our lightweight marker syntax ("## Title").
-	If the title is "Example" or "Examples" (case-insensitive), we extract that
-	section (including its content until the next "##" marker) and return it
-	separately so callers can render it at the end.
+	- preamble: everything before the first "##" section marker
+	- sections: from the first "##" marker to the end
+
+	This is used to control placement: the preamble stays near the top of object
+	documentation, while section blocks (Notes/References/See Also/...) can be
+	placed after intrinsic blocks (Arguments/Returns/Attributes/Procedures).
 	"""
 	if not text:
 		return None, None
 
 	lines = str(text).splitlines()
-	main: list[str] = []
-	examples: list[str] = []
-	i = 0
-	while i < len(lines):
-		line = lines[i]
-		m = _RE_DOC_SECTION.match(line)
-		if not m:
-			main.append(line)
-			i += 1
-			continue
-
-		title = (m.group("title") or "").strip().lower()
-		is_examples = title in {"example", "examples"}
-
-		# Capture this section (header + body until next section header).
-		section_lines: list[str] = [line]
-		i += 1
-		while i < len(lines) and not _RE_DOC_SECTION.match(lines[i]):
-			section_lines.append(lines[i])
-			i += 1
+	first = None
+	for i, line in enumerate(lines):
+		if _RE_DOC_SECTION.match(line):
+			first = i
+			break
 
-		if is_examples:
-			# Ensure examples start on a clean boundary when appended.
-			if examples and examples[-1].strip() != "":
-				examples.append("")
-			examples.extend(section_lines)
-		else:
-			main.extend(section_lines)
+	if first is None:
+		preamble = "\n".join(lines).strip() or None
+		return preamble, None
 
-	main_text = "\n".join(main).strip() or None
-	examples_text = "\n".join(examples).strip() or None
-	return main_text, examples_text
+	preamble = "\n".join(lines[:first]).strip() or None
+	sections = "\n".join(lines[first:]).strip() or None
+	return preamble, sections
 
 
 def _preprocess_fortran_docstring(text: str) -> str:
@@ -546,15 +529,16 @@ def _append_object_description(
 	desc += signode
 
 	content = addnodes.desc_content()
-	main_doc, examples_doc = _split_out_examples_sections(doc)
-	_append_doc(content, main_doc, state)
+	preamble_doc, section_blocks_doc = _split_out_doc_section_blocks(doc)
+	# Keep the opening free-text docstring at the top.
+	_append_doc(content, preamble_doc, state)
 	_append_argument_docs(content, args, state)
 	if objtype == "function":
 		_append_return_docs(content, result, state)
 	_append_component_docs(content, components, state)
 	_append_type_bound_procedures(content, bindings, all_procedures, state)
-	# Always put Examples at the end of the object documentation.
-	_append_doc(content, examples_doc, state)
+	# Place all "## ..." section blocks (including "## Examples") after intrinsic blocks.
+	_append_doc(content, section_blocks_doc, state)
 	desc += content
 
 	section += desc

tests/test_docstring_format.py

@@ -2,7 +2,7 @@
 
 from sphinx_fortran_domain.directives import (
     _preprocess_fortran_docstring,
-    _split_out_examples_sections,
+    _split_out_doc_section_blocks,
 )
 
 
@@ -67,64 +67,50 @@ def test_preprocess_see_also_to_seealso_directive() -> None:
     assert ".. rubric:: Notes" in out
 
 
-def test_split_out_examples_sections_moves_examples_to_end() -> None:
+def test_split_out_doc_section_blocks_includes_examples_in_sections() -> None:
     text = """Summary
 
+Intro paragraph.
+
 ## Examples
 >>> call foo(a)
 
 ## Notes
 Something important.
 """
 
-    main, examples = _split_out_examples_sections(text)
-    assert main and "## Examples" not in main
-    assert "## Notes" in main
-    assert examples and "## Examples" in examples
-
-
-def test_split_out_examples_sections_keeps_non_examples_in_place() -> None:
-    text = """## Notes
-Text.
-"""
-    main, examples = _split_out_examples_sections(text)
-    assert main == text.strip()
-    assert examples is None
+    preamble, sections = _split_out_doc_section_blocks(text)
+    assert preamble and "## Examples" not in preamble
+    assert sections and "## Examples" in sections
+    assert sections and "## Notes" in sections
 
 
-def test_split_out_examples_sections_keeps_fenced_blocks_in_place() -> None:
-    text = """Summary
+def test_split_out_doc_section_blocks_splits_preamble_from_sections() -> None:
+    text = """Short summary line.
 
-```fortran
-print *, 'hello'
-```
+More details.
 
 ## Notes
-More text.
-"""
+Some notes.
 
-    main, examples = _split_out_examples_sections(text)
-    assert main and "```fortran" in main
-    assert "## Notes" in main
-    assert examples is None
+## References
+- A
+"""
 
+    preamble, sections = _split_out_doc_section_blocks(text)
+    assert preamble and "Short summary" in preamble
+    assert preamble and "## Notes" not in preamble
+    assert sections and sections.lstrip().startswith("## Notes")
+    assert sections and "## References" in sections
 
-def test_split_out_examples_sections_moves_examples_section_with_fences() -> None:
-    text = """Summary
 
-## Examples
-```fortran
-print *, 'hello'
-```
+def test_split_out_doc_section_blocks_no_sections_returns_all_preamble() -> None:
+    text = """Just prose.
 
-## Notes
-More text.
+No explicit sections.
 """
-
-    main, examples = _split_out_examples_sections(text)
-    assert main and "## Examples" not in main
-    assert "## Notes" in main
-    assert examples and "## Examples" in examples
-    assert "```fortran" in examples
+    preamble, sections = _split_out_doc_section_blocks(text)
+    assert preamble == text.strip()
+    assert sections is None