Skip to content

Preserve Markdown callout blockquote lines in docbuilder style docstring formatting #756

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
qgallouedec wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Preserve Markdown callout blockquote lines in docbuilder style docstring formatting #756

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
86c11f2
Preserve Markdown callout blockquote lines in `docbuilder style` docs…
qgallouedec Feb 25, 2026
9c3df80
Merge branch 'main' into allow-cite
qgallouedec Feb 25, 2026
d72e49a
Rename test for blockquote regex to reflect tip handling
qgallouedec Feb 25, 2026
fa7a3de
Extend test to multi line
qgallouedec Feb 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/doc_builder/style_doc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@
_re_docstyle_ignore = re.compile(r"#\s*docstyle-ignore")
# Re pattern that matches <Tip>, </Tip> and <Tip warning={true}> blocks.
_re_tip = re.compile(r"^\s*</?Tip(>|\s+warning={true}>)\s*$")
# Re pattern that matches blockquote tip markers: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION]
_re_blockquote_tip = re.compile(r"^\s*> \[!(?:NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*$")
# Re pattern that catches markdown blockquote lines.
_re_blockquote_tip = re.compile(r"^\s*>\s?.*$")
Copy link
Copy Markdown
Contributor

@Wauplin Wauplin Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
_re_blockquote_tip = re.compile(r"^\s*>\s?.*$")
_re_blockquote = re.compile(r"^\s*>\s?.*$")

(nit) (not catching only tips anymore)


DOCTEST_PROMPTS = [">>>", "..."]

Expand Down
28 changes: 28 additions & 0 deletions tests/test_style_doc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
import unittest

from doc_builder.style_doc import (
_re_blockquote_tip,
_re_code,
_re_docstyle_ignore,
_re_list,
Expand Down Expand Up @@ -53,6 +54,11 @@ def test_re_tip(self):
self.assertIsNotNone(_re_tip.search("<Tip warning={true}>"))
self.assertIsNotNone(_re_tip.search(" <Tip warning={true}>"))

def test_re_blockquote_tip(self):
self.assertIsNotNone(_re_blockquote_tip.search("> quoted line"))
self.assertIsNotNone(_re_blockquote_tip.search("> [!NOTE]"))
self.assertIsNotNone(_re_blockquote_tip.search(" > indented quoted line"))

def test_parse_code_example(self):
# One code sample, no output
self.assertEqual(parse_code_example(["code line 1", "code line 2"]), (["code line 1\ncode line 2"], []))
Expand Down Expand Up @@ -176,3 +182,25 @@ def test_format_docstring_handle_params_without_empty_line_after_description(sel
"""

self.assertEqual(style_docstring(test_docstring, 119)[0], expected_result)

def test_format_docstring_keeps_markdown_callout_lines(self):
test_docstring = """Function description

Params:
x (`int`): This is x.

> [!NOTE]
> This is a note.
> This is still part of the note.
"""
expected_result = """Function description

Params:
x (`int`): This is x.

> [!NOTE]
> This is a note.
> This is still part of the note.
"""

self.assertEqual(style_docstring(test_docstring, 119)[0], expected_result)