diff --git a/docs/_quarto.yml b/docs/_quarto.yml index b53e8c70..40c2d9e0 100644 --- a/docs/_quarto.yml +++ b/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 diff --git a/docs/get-started/basic-content.qmd b/docs/get-started/basic-content.qmd index 015776ec..7e8826d3 100644 --- a/docs/get-started/basic-content.qmd +++ b/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. diff --git a/quartodoc/builder/blueprint.py b/quartodoc/builder/blueprint.py index 4f745780..7f73ceb2 100644 --- a/quartodoc/builder/blueprint.py +++ b/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 diff --git a/quartodoc/layout.py b/quartodoc/layout.py index 86b5629f..0b34761c 100644 --- a/quartodoc/layout.py +++ b/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": diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index d8aa1d36..1d81fbb5 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/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]): diff --git a/quartodoc/tests/__snapshots__/test_renderers.ambr b/quartodoc/tests/__snapshots__/test_renderers.ambr index 20a33a8b..77f53256 100644 --- a/quartodoc/tests/__snapshots__/test_renderers.ambr +++ b/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