From 1a708eafc7bde6752db0849c91c6522453d0184f Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 19:58:59 -0400 Subject: [PATCH 01/16] Add desc_first option to MdRenderer --- quartodoc/renderers/md_renderer.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index b36f1bd..38db32c 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -129,6 +129,9 @@ class MdRenderer(Renderer): "full", or "canonical". These options range from just the function name, to its full path relative to its package, to including the package name, to its the its full path relative to its .__module__. + desc_first: bool + Whether to place the description (first line of docstring) before the + object name and signature. Default is False. Examples -------- @@ -154,6 +157,7 @@ def __init__( render_interlinks=False, # table_style="description-list", table_style="table", + desc_first: bool = False, ): self.header_level = header_level self.show_signature = show_signature @@ -162,6 +166,7 @@ def __init__( self.hook_pre = hook_pre self.render_interlinks = render_interlinks self.table_style = table_style + self.desc_first = desc_first self.crnt_header_level = self.header_level From 0c3291b800aed13f368c096120f5be5ba1fca344 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 20:00:22 -0400 Subject: [PATCH 02/16] Add method to extract first docstring paragraph --- quartodoc/renderers/md_renderer.py | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index 38db32c..79163f7 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -178,6 +178,24 @@ def _increment_header(self, n=1): finally: self.crnt_header_level -= n + def _extract_description(self, el: Union[dc.Object, dc.Alias]) -> Optional[str]: + if el.docstring is None: + return None + + patched_sections = qast.transform(el.docstring.parsed) + + for section in patched_sections: + title = section.title or section.kind.value + if title == "text": + # Get the raw text value from the section + text = section.value if hasattr(section, 'value') else "" + if text: + # Split on double newline to get first paragraph + paragraphs = text.split('\n\n') + return paragraphs[0].strip() if paragraphs else None + + return None + def _fetch_object_dispname(self, el: "dc.Alias | dc.Object"): # TODO: copied from Builder, should move into util function if self.display_name in {"name", "short"}: From f7fd79160709defac42e3b02e987f62f12375d2b Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 20:00:40 -0400 Subject: [PATCH 03/16] Add method to render docstring without first paragraph --- quartodoc/renderers/md_renderer.py | 35 ++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index 79163f7..49ec7f4 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -196,6 +196,41 @@ def _extract_description(self, el: Union[dc.Object, dc.Alias]) -> Optional[str]: return None + def _render_without_first_paragraph(self, el: Union[dc.Object, dc.Alias]) -> str: + if el.docstring is None: + return "" + + str_body = [] + patched_sections = qast.transform(el.docstring.parsed) + first_text_seen = False + + for section in patched_sections: + title = section.title or section.kind.value + + # Handle the first text section specially + if title == "text" and not first_text_seen: + first_text_seen = True + # Get remaining paragraphs after the first one + text = section.value if hasattr(section, 'value') else "" + if text: + paragraphs = text.split('\n\n') + if len(paragraphs) > 1: + # Join remaining paragraphs and add them + remaining = '\n\n'.join(paragraphs[1:]).strip() + if remaining: + str_body.append(remaining) + continue + + body: str = self.render(section) + + if title != "text": + header = self.render_header(section) + str_body.append("\n\n".join([header, body])) + else: + str_body.append(body) + + return "\n\n".join(str_body) + def _fetch_object_dispname(self, el: "dc.Alias | dc.Object"): # TODO: copied from Builder, should move into util function if self.display_name in {"name", "short"}: From 63c2a20341301734cc61078e970149ca7afd380c Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 20:06:22 -0400 Subject: [PATCH 04/16] Add desc_first option to MdRenderer rendering --- quartodoc/renderers/md_renderer.py | 32 +++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index 49ec7f4..94750e2 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -511,12 +511,34 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]): str_sig = self.signature(el) sig_part = [str_sig] if self.show_signature else [] - with self._increment_header(): - body = self.render(el.obj) + # Check for desc_first on the element first, then fall back to renderer default + desc_first = getattr(el, 'desc_first', None) + if desc_first is None: + desc_first = self.desc_first + + if desc_first: + # Extract first paragraph as description + desc = self._extract_description(el.obj) + + with self._increment_header(): + # Render body without first paragraph + body = self._render_without_first_paragraph(el.obj) + + # Reorder to get description, title, signature, rest of body, members + if desc: + # If body is not empty, include it; otherwise, don't include it + parts = ([desc, title, *sig_part, body, *attr_docs, *class_docs, *meth_docs] if body + else [desc, title, *sig_part, *attr_docs, *class_docs, *meth_docs]) + else: + # Case with no description extracted + parts = [title, *sig_part, body, *attr_docs, *class_docs, *meth_docs] + else: + with self._increment_header(): + body = self.render(el.obj) + + parts = [title, *sig_part, body, *attr_docs, *class_docs, *meth_docs] - return "\n\n".join( - [title, *sig_part, body, *attr_docs, *class_docs, *meth_docs] - ) + return "\n\n".join(parts) @dispatch def render(self, el: Union[layout.DocFunction, layout.DocAttribute]): From ab6339aedffe53a1f23398cae4443021c08eba16 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 20:07:04 -0400 Subject: [PATCH 05/16] Support the desc_first option in MdRenderer --- quartodoc/renderers/md_renderer.py | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index 94750e2..21e7c81 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -547,10 +547,31 @@ def render(self, el: Union[layout.DocFunction, layout.DocAttribute]): str_sig = self.signature(el) sig_part = [str_sig] if self.show_signature else [] - with self._increment_header(): - body = self.render(el.obj) + # Check for desc_first on the element first, then fall back to renderer default + desc_first = getattr(el, 'desc_first', None) + if desc_first is None: + desc_first = self.desc_first + + if desc_first: + # Extract first paragraph as description + desc = self._extract_description(el.obj) + + with self._increment_header(): + # Render body without the first paragraph + body = self._render_without_first_paragraph(el.obj) + + # Reorder: description, title, signature, rest of body + if desc: + parts = [desc, title, *sig_part, body] if body else [desc, title, *sig_part] + else: + parts = [title, *sig_part, body] + else: + with self._increment_header(): + body = self.render(el.obj) + + parts = [title, *sig_part, body] - return "\n\n".join([title, *sig_part, body]) + return "\n\n".join(parts) # render griffe objects =================================================== From 0deb0ef28fce15c10ee2bae1207f1524dc3115f0 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 20:07:21 -0400 Subject: [PATCH 06/16] Add desc_first option to AutoOptions and Doc classes --- quartodoc/layout.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/quartodoc/layout.py b/quartodoc/layout.py index dcd8db6..94a36b5 100644 --- a/quartodoc/layout.py +++ b/quartodoc/layout.py @@ -227,6 +227,7 @@ class AutoOptions(_Base): package: Union[str, None, MISSING] = MISSING() member_order: Literal["alphabetical", "source"] = "alphabetical" member_options: Optional["AutoOptions"] = None + desc_first: bool = False # for tracking fields users manually specify # so we can tell them apart from defaults @@ -344,6 +345,7 @@ class Doc(_Docable): obj: Union[dc.Object, dc.Alias] anchor: str signature_name: SignatureOptions = "relative" + desc_first: Optional[bool] = None class Config: arbitrary_types_allowed = True @@ -358,6 +360,7 @@ def from_griffe( anchor: str = None, flat: bool = False, signature_name: str = "relative", + desc_first: Optional[bool] = None, ): if members is None: members = [] @@ -370,6 +373,7 @@ def from_griffe( "obj": obj, "anchor": anchor, "signature_name": signature_name, + "desc_first": desc_first, } if kind == "function": From 8a4ace27e155cfee2ee55bb7c74ad9a391d7910e Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 20:08:31 -0400 Subject: [PATCH 07/16] Pass desc_first to Doc only if explicitly set --- quartodoc/builder/blueprint.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/quartodoc/builder/blueprint.py b/quartodoc/builder/blueprint.py index e796a89..0d2d770 100644 --- a/quartodoc/builder/blueprint.py +++ b/quartodoc/builder/blueprint.py @@ -350,12 +350,20 @@ def enter(self, el: Auto): children.append(res) is_flat = el.children == ChoicesChildren.flat + + # Only pass desc_first if it was explicitly set by the user + kwargs = { + "flat": is_flat, + "signature_name": el.signature_name, + } + if "desc_first" in el._fields_specified: + kwargs["desc_first"] = el.desc_first + return Doc.from_griffe( el.name, obj, children, - flat=is_flat, - signature_name=el.signature_name, + **kwargs ) def _fetch_members(self, el: Auto, obj: dc.Object | dc.Alias): From 6ce3edd6c9d3f085fb0b3f3d7d3d8ef97551f4fb Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 20:08:50 -0400 Subject: [PATCH 08/16] Add test for desc_first rendering in MdRenderer --- quartodoc/tests/test_renderers.py | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/quartodoc/tests/test_renderers.py b/quartodoc/tests/test_renderers.py index ee241f2..3e68f31 100644 --- a/quartodoc/tests/test_renderers.py +++ b/quartodoc/tests/test_renderers.py @@ -247,3 +247,23 @@ def test_render_numpydoc_section_return(snapshot, doc): assert snapshot == indented_sections( Code=full_doc, Default=res_default, List=res_list ) + + +# desc_first tests ------------------------------------------------------------ + + +def test_render_desc_first_function(): + auto = Auto(name="a_func", package="quartodoc.tests.example", desc_first=True) + bp = blueprint(auto) + + renderer = MdRenderer() + result = renderer.render(bp) + + # The result should have: description, then title, then signature, then rest + desc_pos = result.find("A function") + title_pos = result.find("# a_func") + + assert desc_pos != -1 + assert title_pos != -1 + assert desc_pos < title_pos + From 12478137c024e02a61b50059935ba70789255470 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 20:09:20 -0400 Subject: [PATCH 09/16] Add several tests for desc_first in MdRenderer --- quartodoc/tests/test_renderers.py | 48 +++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/quartodoc/tests/test_renderers.py b/quartodoc/tests/test_renderers.py index 3e68f31..e8cb34b 100644 --- a/quartodoc/tests/test_renderers.py +++ b/quartodoc/tests/test_renderers.py @@ -267,3 +267,51 @@ def test_render_desc_first_function(): assert title_pos != -1 assert desc_pos < title_pos + +def test_render_desc_first_false(): + auto = Auto(name="a_func", package="quartodoc.tests.example", desc_first=False) + bp = blueprint(auto) + + renderer = MdRenderer() + result = renderer.render(bp) + + # The result should have: title, signature, then description + desc_pos = result.find("A function") + title_pos = result.find("# a_func") + + assert desc_pos != -1 + assert title_pos != -1 + assert title_pos < desc_pos + + +def test_render_desc_first_class(): + auto = Auto(name="AClass", package="quartodoc.tests.example", desc_first=True) + bp = blueprint(auto) + + renderer = MdRenderer() + result = renderer.render(bp) + + # Check that "A class" (description) appears before "# AClass" (title) + desc_pos = result.find("A class") + title_pos = result.find("# AClass") + + assert desc_pos != -1 + assert title_pos != -1 + assert desc_pos < title_pos + + +def test_render_desc_first_renderer_default(): + auto = Auto(name="a_func", package="quartodoc.tests.example") + bp = blueprint(auto) + + # Renderer with desc_first=True as default + renderer = MdRenderer(desc_first=True) + result = renderer.render(bp) + + # Check that description comes before title + desc_pos = result.find("A function") + title_pos = result.find("# a_func") + + assert desc_pos != -1 + assert title_pos != -1 + assert desc_pos < title_pos From 8646904c4efe007d43344e5449be3c6bc1cd9fbf Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 22:07:20 -0400 Subject: [PATCH 10/16] Fix order of rendered docstring parts with desc_first --- quartodoc/renderers/md_renderer.py | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index 21e7c81..7b8504f 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -130,8 +130,9 @@ class MdRenderer(Renderer): full path relative to its package, to including the package name, to its the its full path relative to its .__module__. desc_first: bool - Whether to place the description (first line of docstring) before the - object name and signature. Default is False. + Whether to place the description (first paragraph of docstring) after the + object name and before the signature. When True, the order is: title, + description, signature, remaining content. Default is False. Examples -------- @@ -524,11 +525,11 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]): # Render body without first paragraph body = self._render_without_first_paragraph(el.obj) - # Reorder to get description, title, signature, rest of body, members + # Reorder to get title, description, signature, rest of body, members if desc: # If body is not empty, include it; otherwise, don't include it - parts = ([desc, title, *sig_part, body, *attr_docs, *class_docs, *meth_docs] if body - else [desc, title, *sig_part, *attr_docs, *class_docs, *meth_docs]) + parts = ([title, desc, *sig_part, body, *attr_docs, *class_docs, *meth_docs] if body + else [title, desc, *sig_part, *attr_docs, *class_docs, *meth_docs]) else: # Case with no description extracted parts = [title, *sig_part, body, *attr_docs, *class_docs, *meth_docs] @@ -560,9 +561,9 @@ def render(self, el: Union[layout.DocFunction, layout.DocAttribute]): # Render body without the first paragraph body = self._render_without_first_paragraph(el.obj) - # Reorder: description, title, signature, rest of body + # Reorder: title, description, signature, rest of body if desc: - parts = [desc, title, *sig_part, body] if body else [desc, title, *sig_part] + parts = [title, desc, *sig_part, body] if body else [title, desc, *sig_part] else: parts = [title, *sig_part, body] else: From ee9441d398b6d8c1c8ca95f4c79a0c59a1c7efff Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 22:07:23 -0400 Subject: [PATCH 11/16] Update test_renderers.py --- quartodoc/tests/test_renderers.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/quartodoc/tests/test_renderers.py b/quartodoc/tests/test_renderers.py index e8cb34b..a153bef 100644 --- a/quartodoc/tests/test_renderers.py +++ b/quartodoc/tests/test_renderers.py @@ -259,13 +259,13 @@ def test_render_desc_first_function(): renderer = MdRenderer() result = renderer.render(bp) - # The result should have: description, then title, then signature, then rest + # The result should have: title, then description, then signature, then rest desc_pos = result.find("A function") title_pos = result.find("# a_func") assert desc_pos != -1 assert title_pos != -1 - assert desc_pos < title_pos + assert title_pos < desc_pos def test_render_desc_first_false(): @@ -291,13 +291,13 @@ def test_render_desc_first_class(): renderer = MdRenderer() result = renderer.render(bp) - # Check that "A class" (description) appears before "# AClass" (title) + # Check that "# AClass" (title) appears before "A class" (description) desc_pos = result.find("A class") title_pos = result.find("# AClass") assert desc_pos != -1 assert title_pos != -1 - assert desc_pos < title_pos + assert title_pos < desc_pos def test_render_desc_first_renderer_default(): @@ -308,10 +308,10 @@ def test_render_desc_first_renderer_default(): renderer = MdRenderer(desc_first=True) result = renderer.render(bp) - # Check that description comes before title + # Check that title comes before description desc_pos = result.find("A function") title_pos = result.find("# a_func") assert desc_pos != -1 assert title_pos != -1 - assert desc_pos < title_pos + assert title_pos < desc_pos From a0fef5ccb3460ff134a35dd08f6d01e1645b8c47 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 22:42:19 -0400 Subject: [PATCH 12/16] Wrap description in styled div --- quartodoc/renderers/md_renderer.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index 7b8504f..10c6776 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -527,9 +527,11 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]): # Reorder to get title, description, signature, rest of body, members if desc: + # Wrap description in a div with class for styling + desc_wrapped = f'::: {{.lead}}\n{desc}\n:::' # If body is not empty, include it; otherwise, don't include it - parts = ([title, desc, *sig_part, body, *attr_docs, *class_docs, *meth_docs] if body - else [title, desc, *sig_part, *attr_docs, *class_docs, *meth_docs]) + parts = ([title, desc_wrapped, *sig_part, body, *attr_docs, *class_docs, *meth_docs] if body + else [title, desc_wrapped, *sig_part, *attr_docs, *class_docs, *meth_docs]) else: # Case with no description extracted parts = [title, *sig_part, body, *attr_docs, *class_docs, *meth_docs] @@ -563,7 +565,9 @@ def render(self, el: Union[layout.DocFunction, layout.DocAttribute]): # Reorder: title, description, signature, rest of body if desc: - parts = [title, desc, *sig_part, body] if body else [title, desc, *sig_part] + # Wrap description in a div with class for styling + desc_wrapped = f'::: {{.lead}}\n{desc}\n:::' + parts = [title, desc_wrapped, *sig_part, body] if body else [title, desc_wrapped, *sig_part] else: parts = [title, *sig_part, body] else: From 78a505547c596b3228118d090569a4ee8fb3e2e8 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 23:19:57 -0400 Subject: [PATCH 13/16] Add inline styles to description wrapper in MdRenderer --- quartodoc/renderers/md_renderer.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index 10c6776..269902c 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -527,8 +527,8 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]): # Reorder to get title, description, signature, rest of body, members if desc: - # Wrap description in a div with class for styling - desc_wrapped = f'::: {{.lead}}\n{desc}\n:::' + # Wrap description in a div with inline styles + desc_wrapped = f'::: {{.lead style="font-style: italic; margin-top: -10px;"}}\n{desc}\n:::' # If body is not empty, include it; otherwise, don't include it parts = ([title, desc_wrapped, *sig_part, body, *attr_docs, *class_docs, *meth_docs] if body else [title, desc_wrapped, *sig_part, *attr_docs, *class_docs, *meth_docs]) @@ -565,8 +565,8 @@ def render(self, el: Union[layout.DocFunction, layout.DocAttribute]): # Reorder: title, description, signature, rest of body if desc: - # Wrap description in a div with class for styling - desc_wrapped = f'::: {{.lead}}\n{desc}\n:::' + # Wrap description in a div with inline styles + desc_wrapped = f'::: {{.lead style="font-style: italic; margin-top: -10px;"}}\n{desc}\n:::' parts = [title, desc_wrapped, *sig_part, body] if body else [title, desc_wrapped, *sig_part] else: parts = [title, *sig_part, body] From 0a3b538713a7faecf25f1f53abc2d43cd8008beb Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Thu, 30 Oct 2025 23:43:22 -0400 Subject: [PATCH 14/16] Specify font size --- quartodoc/renderers/md_renderer.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index 269902c..0c76337 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -566,7 +566,7 @@ def render(self, el: Union[layout.DocFunction, layout.DocAttribute]): # Reorder: title, description, signature, rest of body if desc: # Wrap description in a div with inline styles - desc_wrapped = f'::: {{.lead style="font-style: italic; margin-top: -10px;"}}\n{desc}\n:::' + desc_wrapped = f'::: {{.lead style="font-size: 1rem; font-style: italic; margin-top: -10px;"}}\n{desc}\n:::' parts = [title, desc_wrapped, *sig_part, body] if body else [title, desc_wrapped, *sig_part] else: parts = [title, *sig_part, body] From e2121b70b4f5b4ee5a4a32422728baf34dcd87ff Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Fri, 31 Oct 2025 00:07:28 -0400 Subject: [PATCH 15/16] Add line-height style --- quartodoc/renderers/md_renderer.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index 0c76337..cad70ab 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -566,7 +566,7 @@ def render(self, el: Union[layout.DocFunction, layout.DocAttribute]): # Reorder: title, description, signature, rest of body if desc: # Wrap description in a div with inline styles - desc_wrapped = f'::: {{.lead style="font-size: 1rem; font-style: italic; margin-top: -10px;"}}\n{desc}\n:::' + desc_wrapped = f'::: {{.lead style="font-size: 1rem; font-style: italic; margin-top: -10px; line-height: 1;"}}\n{desc}\n:::' parts = [title, desc_wrapped, *sig_part, body] if body else [title, desc_wrapped, *sig_part] else: parts = [title, *sig_part, body] From b01e75cdea4d3a46035b407baccd0d5276e7d4df Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Fri, 7 Nov 2025 11:15:26 -0500 Subject: [PATCH 16/16] Update formatting to pass linting checks --- quartodoc/builder/blueprint.py | 11 +++-------- quartodoc/tests/test_renderers.py | 18 +++++++++--------- 2 files changed, 12 insertions(+), 17 deletions(-) diff --git a/quartodoc/builder/blueprint.py b/quartodoc/builder/blueprint.py index 0d2d770..b95b41e 100644 --- a/quartodoc/builder/blueprint.py +++ b/quartodoc/builder/blueprint.py @@ -350,7 +350,7 @@ def enter(self, el: Auto): children.append(res) is_flat = el.children == ChoicesChildren.flat - + # Only pass desc_first if it was explicitly set by the user kwargs = { "flat": is_flat, @@ -358,13 +358,8 @@ def enter(self, el: Auto): } if "desc_first" in el._fields_specified: kwargs["desc_first"] = el.desc_first - - return Doc.from_griffe( - el.name, - obj, - children, - **kwargs - ) + + return Doc.from_griffe(el.name, obj, children, **kwargs) def _fetch_members(self, el: Auto, obj: dc.Object | dc.Alias): # Note that this could be a static method, if we passed in the griffe loader diff --git a/quartodoc/tests/test_renderers.py b/quartodoc/tests/test_renderers.py index a153bef..35c5e37 100644 --- a/quartodoc/tests/test_renderers.py +++ b/quartodoc/tests/test_renderers.py @@ -255,14 +255,14 @@ def test_render_numpydoc_section_return(snapshot, doc): def test_render_desc_first_function(): auto = Auto(name="a_func", package="quartodoc.tests.example", desc_first=True) bp = blueprint(auto) - + renderer = MdRenderer() result = renderer.render(bp) - + # The result should have: title, then description, then signature, then rest desc_pos = result.find("A function") title_pos = result.find("# a_func") - + assert desc_pos != -1 assert title_pos != -1 assert title_pos < desc_pos @@ -271,10 +271,10 @@ def test_render_desc_first_function(): def test_render_desc_first_false(): auto = Auto(name="a_func", package="quartodoc.tests.example", desc_first=False) bp = blueprint(auto) - + renderer = MdRenderer() result = renderer.render(bp) - + # The result should have: title, signature, then description desc_pos = result.find("A function") title_pos = result.find("# a_func") @@ -287,10 +287,10 @@ def test_render_desc_first_false(): def test_render_desc_first_class(): auto = Auto(name="AClass", package="quartodoc.tests.example", desc_first=True) bp = blueprint(auto) - + renderer = MdRenderer() result = renderer.render(bp) - + # Check that "# AClass" (title) appears before "A class" (description) desc_pos = result.find("A class") title_pos = result.find("# AClass") @@ -303,11 +303,11 @@ def test_render_desc_first_class(): def test_render_desc_first_renderer_default(): auto = Auto(name="a_func", package="quartodoc.tests.example") bp = blueprint(auto) - + # Renderer with desc_first=True as default renderer = MdRenderer(desc_first=True) result = renderer.render(bp) - + # Check that title comes before description desc_pos = result.find("A function") title_pos = result.find("# a_func")