Merge branch 'main' into feat-auto-exclude

Author: machow

quartodoc/builder/blueprint.py

@@ -407,7 +407,12 @@ def _fetch_members(self, el: Auto, obj: dc.Object | dc.Alias):
         if el.exclude:
             options = {k: v for k, v in options.items() if k not in el.exclude}
 
-        return sorted(options)
+        if el.member_order == "alphabetical":
+            return sorted(options)
+        elif el.member_order == "source":
+            return list(options)
+        else:
+            raise ValueError(f"Unsupported value of member_order: {el.member_order}")
 
 
 class _PagePackageStripper(PydanticTransformer):

quartodoc/layout.py

@@ -225,6 +225,7 @@ class AutoOptions(_Base):
     dynamic: Union[None, bool, str] = None
     children: ChoicesChildren = ChoicesChildren.embedded
     package: Union[str, None, MISSING] = MISSING()
+    member_order: Literal["alphabetical", "source"] = "alphabetical"
     member_options: Optional["AutoOptions"] = None
 
     # for tracking fields users manually specify
@@ -277,6 +278,9 @@ class Auto(AutoOptions):
         Style for presenting members. Either separate, embedded, or flat.
     package:
         If specified, object lookup will be relative to this path.
+    member_order:
+        Order to present members in, either "alphabetical" or "source" order.
+        Defaults to alphabetical sorting.
     member_options:
         Options to apply to members. These can include any of the options above.
 

quartodoc/renderers/md_renderer.py

@@ -59,7 +59,7 @@ class ParamRow:
     def to_definition_list(self):
         name = self.name
         anno = self.annotation
-        desc = self.description
+        desc = sanitize(self.description, allow_markdown=True)
         default = sanitize(str(self.default))
 
         part_name = (
@@ -77,7 +77,7 @@ def to_definition_list(self):
         # in the table display format, not description lists....
         # by this stage _required_ is basically a special token to indicate
         # a required argument.
-        if default is not None:
+        if self.default is not None:
             part_default_sep = Span(" = ", Attr(classes=["parameter-default-sep"]))
             part_default = Span(default, Attr(classes=["parameter-default"]))
         else:
@@ -100,13 +100,15 @@ def to_definition_list(self):
 
     def to_tuple(self, style: Literal["parameters", "attributes", "returns"]):
         name = self.name
+        description = sanitize(self.description, allow_markdown=True)
+
         if style == "parameters":
             default = "_required_" if self.default is None else escape(self.default)
-            return (name, self.annotation, self.description, default)
+            return (name, self.annotation, description, default)
         elif style == "attributes":
-            return (name, self.annotation, self.description)
+            return (name, self.annotation, description)
         elif style == "returns":
-            return (name, self.annotation, self.description)
+            return (name, self.annotation, description)
 
         raise NotImplementedError(f"Unsupported table style: {style}")
 
@@ -595,8 +597,9 @@ def render(self, el: ds.DocstringSectionParameters):
     @dispatch
     def render(self, el: ds.DocstringParameter) -> ParamRow:
         annotation = self.render_annotation(el.annotation)
-        clean_desc = sanitize(el.description, allow_markdown=True)
-        return ParamRow(el.name, clean_desc, annotation=annotation, default=el.default)
+        return ParamRow(
+            el.name, el.description, annotation=annotation, default=el.default
+        )
 
     # attributes ----
 
@@ -611,7 +614,7 @@ def render(self, el: ds.DocstringSectionAttributes):
     def render(self, el: ds.DocstringAttribute) -> ParamRow:
         return ParamRow(
             el.name,
-            sanitize(el.description or "", allow_markdown=True),
+            el.description or "",
             annotation=self.render_annotation(el.annotation),
         )
 
@@ -680,7 +683,7 @@ def render(self, el: ds.DocstringReturn):
         # similar to DocstringParameter, but no name or default
         return ParamRow(
             el.name,
-            sanitize(el.description, allow_markdown=True),
+            el.description,
             annotation=self.render_annotation(el.annotation),
         )
 
@@ -689,7 +692,7 @@ def render(self, el: ds.DocstringRaise) -> ParamRow:
         # similar to DocstringParameter, but no name or default
         return ParamRow(
             None,
-            sanitize(el.description, allow_markdown=True),
+            el.description,
             annotation=self.render_annotation(el.annotation),
         )
 

quartodoc/tests/__snapshots__/test_renderers.ambr

@@ -483,19 +483,19 @@
   List
       # Parameters {.doc-section .doc-section-parameters}
 
-      <code>[**int**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
+      <code>[**int**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation}</code>
 
       :   A description.
 
       # Returns {.doc-section .doc-section-returns}
 
-      <code>[]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
+      <code>[]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation}</code>
 
       :   A description.
 
       # Attributes {.doc-section .doc-section-attributes}
 
-      <code>[**int**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
+      <code>[**int**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation}</code>
 
       :   A description.
   '''
@@ -540,19 +540,19 @@
   List
       # Parameters {.doc-section .doc-section-parameters}
 
-      <code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
+      <code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation}</code>
 
       :   A description.
 
       # Returns {.doc-section .doc-section-returns}
 
-      <code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
+      <code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation}</code>
 
       :   A description.
 
       # Attributes {.doc-section .doc-section-attributes}
 
-      <code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
+      <code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation}</code>
 
       :   A description.
   '''

quartodoc/tests/test_builder_blueprint.py

@@ -284,6 +284,25 @@ def test_blueprint_fetch_members_dynamic():
     assert bp.members[0].obj.parent.path == name.replace(":", ".")
 
 
+@pytest.mark.parametrize("order", ["alphabetical", "source"])
+def test_blueprint_member_order(order):
+    auto = lo.Auto(
+        name="quartodoc.tests.example_class.C",
+        member_order=order,
+        include_functions=True,
+        include_attributes=False,
+        include_classes=False,
+    )
+    bp = blueprint(auto)
+    src_names = [entry.name for entry in bp.members]
+    dst_names = ["some_method", "some_class_method"]
+
+    if order == "alphabetical":
+        dst_names = sorted(dst_names)
+
+    assert src_names == dst_names
+
+
 def test_blueprint_member_options():
     auto = lo.Auto(
         name="quartodoc.tests.example",