show base classes

docs/_quarto.yml

@@ -80,6 +80,8 @@ quartodoc:
   style: pkgdown
   dir: api
   package: quartodoc
+  options: &defaults
+    show_bases: true
   render_interlinks: true
   sidebar: "api/_sidebar.yml"
   sections:
@@ -98,6 +100,7 @@ quartodoc:
       desc: |
         Renderers convert parsed docstrings into a target format, like markdown.
       options:
+        <<: *defaults
         dynamic: true
       contents:
         - name: MdRenderer

docs/get-started/basic-content.qmd

@@ -173,10 +173,25 @@ The code above uses `&no-members` to name the options in the first section "no-m
 then `*no-members` to reference it in the second section.
 The `&` and `*` are called an anchor and alias, respectively, in YAML.
 
+If you want to extend some options, you can use YAML merge keys:
+
+```yaml
+- options: &short-name
+    display_name: "short"
+- options:
+    <<: *short-name
+    include_functions: false
+    include_attributes: false
+```
+
+In the example above, the `&short-name` options get re-used as part of the second options.
+
 
 ### Where to put options
 
 You can specify options in either the top-level config, or individual Sections.
+Note that if both are set, the options do not get combined.
+Instead, only the options specified at the most specific level are used.
 
 ```yaml
 quartodoc:
@@ -191,13 +206,14 @@ quartodoc:
         - MdRenderer
 
       # set options in an individual section.
-      # in thise case, it resets include_attributes back
-      # to defaulting as true
+      # in thise case, these options are used for this section,
+      # and the options set at the top-level config are not used.
+      # So, include_attributes from the options above is not used.
       options:
-        include_attributes: true
-
+        signature_name: short
 ```
 
+
 ## Specifying package path
 
 Different levels of configuration let you set the `package` option.

quartodoc/builder/blueprint.py

@@ -330,6 +330,7 @@ def enter(self, el: Auto):
             children,
             flat=is_flat,
             signature_name=el.signature_name,
+            show_bases=el.show_bases,
         )
 
     @staticmethod

quartodoc/layout.py

@@ -226,6 +226,7 @@ class AutoOptions(_Base):
     children: ChoicesChildren = ChoicesChildren.embedded
     package: Union[str, None, MISSING] = MISSING()
     member_options: Optional["AutoOptions"] = None
+    show_bases: bool = False
 
     # for tracking fields users manually specify
     # so we can tell them apart from defaults
@@ -274,7 +275,8 @@ class Auto(AutoOptions):
         If specified, object lookup will be relative to this path.
     member_options:
         Options to apply to members. These can include any of the options above.
-
+    show_bases:
+        Whether to show the names base classes of a class.
 
     """
 
@@ -336,6 +338,7 @@ class Doc(_Docable):
     obj: Union[dc.Object, dc.Alias]
     anchor: str
     signature_name: SignatureOptions = "relative"
+    show_bases: bool = False
 
     class Config:
         arbitrary_types_allowed = True
@@ -350,6 +353,7 @@ def from_griffe(
         anchor: str = None,
         flat: bool = False,
         signature_name: str = "relative",
+        show_bases: bool = False,
     ):
         if members is None:
             members = []
@@ -362,6 +366,7 @@ def from_griffe(
             "obj": obj,
             "anchor": anchor,
             "signature_name": signature_name,
+            "show_bases": show_bases,
         }
 
         if kind == "function":

quartodoc/renderers/md_renderer.py

@@ -135,7 +135,7 @@ def render_annotation(self, el: expr.Name) -> str:
         # unescaped pipes screw up table formatting
         if self.render_interlinks:
             return f"[{sanitize(el.source)}](`{el.full}`)"
-        
+
         return sanitize(el.source)
 
     @dispatch
@@ -158,8 +158,6 @@ def signature(self, el: layout.Doc):
 
         return res
 
-
-
     @dispatch
     def signature(self, el: dc.Alias, source: Optional[dc.Alias] = None):
         """Return a string representation of an object's signature."""
@@ -283,6 +281,9 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]):
         attr_docs = []
         meth_docs = []
         class_docs = []
+        bases = ""
+        if el.show_bases and el.obj.is_class and el.obj.bases:
+            bases = f"\n\nBases: `{'`, '.join([x.source for x in el.obj.bases])}`"
 
         if el.members:
             sub_header = "#" * (self.crnt_header_level + 1)
@@ -341,14 +342,14 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]):
                         [self.render(x) for x in raw_meths if isinstance(x, layout.Doc)]
                     )
 
-
         str_sig = self.signature(el)
         sig_part = [str_sig] if self.show_signature else []
 
         body = self.render(el.obj)
 
-
-        return "\n\n".join([title, *sig_part, body, *attr_docs, *class_docs, *meth_docs])
+        return "\n\n".join(
+            [title, *sig_part, bases, body, *attr_docs, *class_docs, *meth_docs]
+        )
 
     @dispatch
     def render(self, el: Union[layout.DocFunction, layout.DocAttribute]):

quartodoc/tests/__snapshots__/test_renderers.ambr

@@ -18,6 +18,8 @@
 
   `tests.example_class.C(self, x, y)`
 
+
+
   The short summary.
 
   The extended summary,
@@ -48,6 +50,8 @@
 
   `tests.example_class.C.D()`
 
+
+
   A nested class
 
   ## Methods
@@ -76,6 +80,8 @@
 
   `tests.example_class.C(self, x, y)`
 
+
+
   The short summary.
 
   The extended summary,
@@ -106,6 +112,8 @@
 
   `tests.example_class.C.D()`
 
+
+
   A nested class
 
   ## Methods
@@ -134,6 +142,8 @@
 
   `tests.example_class.AttributesTable(self)`
 
+
+
   The short summary.
 
   ## Attributes
@@ -151,6 +161,8 @@
 
   `tests.example`
 
+
+
   A module
 
   ## Attributes
@@ -169,6 +181,8 @@
 
   `tests.example.AClass()`
 
+
+
   A class
 
   #### Attributes
@@ -208,6 +222,8 @@
 
   `tests.example`
 
+
+
   A module
 
   ## Attributes
@@ -226,6 +242,8 @@
 
   `tests.example.AClass()`
 
+
+
   A class
 
   ### Attributes