From 1aa33cb620e96bff7742565f5ce4e103f586317b Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Thu, 31 Aug 2023 16:58:27 -0700 Subject: [PATCH 1/6] add show_base --- quartodoc/builder/blueprint.py | 1 + quartodoc/layout.py | 7 ++++++- quartodoc/renderers/md_renderer.py | 5 ++++- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/quartodoc/builder/blueprint.py b/quartodoc/builder/blueprint.py index d7d411de..6dcad227 100644 --- a/quartodoc/builder/blueprint.py +++ b/quartodoc/builder/blueprint.py @@ -332,6 +332,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..c9ddbda8 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 e971481d..47ce57dd 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -275,6 +275,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) @@ -340,7 +343,7 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]): 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]): From 52c6d09bcc36fca104684c6332bf31c3ac10609d Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Thu, 31 Aug 2023 18:08:44 -0700 Subject: [PATCH 2/6] add show_Bases --- docs/_quarto.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 6c7a4bad..2d3876ba 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -80,6 +80,8 @@ quartodoc: style: pkgdown dir: api package: quartodoc + options: + show_bases: true render_interlinks: true sidebar: "api/_sidebar.yml" sections: From a57e1360be6ef63ed7ceb760103eb79dde6a3549 Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Thu, 31 Aug 2023 21:26:58 -0700 Subject: [PATCH 3/6] update snapshots --- .../tests/__snapshots__/test_renderers.ambr | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/quartodoc/tests/__snapshots__/test_renderers.ambr b/quartodoc/tests/__snapshots__/test_renderers.ambr index 44865eb6..8b64a858 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 @@ -69,6 +73,8 @@ `tests.example_class.C(self, x, y)` + + The short summary. The extended summary, @@ -99,6 +105,8 @@ `tests.example_class.C.D()` + + A nested class ## Methods @@ -120,6 +128,8 @@ `tests.example_class.AttributesTable(self)` + + The short summary. ## Attributes @@ -137,6 +147,8 @@ `tests.example` + + A module ## Attributes @@ -155,6 +167,8 @@ `tests.example.AClass()` + + A class #### Attributes @@ -194,6 +208,8 @@ `tests.example` + + A module ## Attributes @@ -212,6 +228,8 @@ `tests.example.AClass()` + + A class ### Attributes From 2ba7d415364f41b008dabe8d03d0c760bc8799ba Mon Sep 17 00:00:00 2001 From: Hamel Husain Date: Thu, 31 Aug 2023 21:52:10 -0700 Subject: [PATCH 4/6] apply black --- quartodoc/builder/blueprint.py | 2 +- quartodoc/layout.py | 2 +- quartodoc/renderers/md_renderer.py | 12 +++++------- 3 files changed, 7 insertions(+), 9 deletions(-) diff --git a/quartodoc/builder/blueprint.py b/quartodoc/builder/blueprint.py index 6dcad227..5e20f0a7 100644 --- a/quartodoc/builder/blueprint.py +++ b/quartodoc/builder/blueprint.py @@ -332,7 +332,7 @@ def enter(self, el: Auto): children, flat=is_flat, signature_name=el.signature_name, - show_bases=el.show_bases + show_bases=el.show_bases, ) @staticmethod diff --git a/quartodoc/layout.py b/quartodoc/layout.py index c9ddbda8..0b34761c 100644 --- a/quartodoc/layout.py +++ b/quartodoc/layout.py @@ -353,7 +353,7 @@ def from_griffe( anchor: str = None, flat: bool = False, signature_name: str = "relative", - show_bases: bool = False + show_bases: bool = False, ): if members is None: members = [] diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py index 47ce57dd..7f4796af 100644 --- a/quartodoc/renderers/md_renderer.py +++ b/quartodoc/renderers/md_renderer.py @@ -127,7 +127,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 @@ -150,8 +150,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.""" @@ -275,7 +273,7 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]): attr_docs = [] meth_docs = [] class_docs = [] - bases='' + 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])}`" @@ -336,14 +334,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, bases, 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]): From 86739033300840450eda83fb5c4b5db674ef3683 Mon Sep 17 00:00:00 2001 From: Michael Chow Date: Mon, 11 Sep 2023 11:22:26 -0400 Subject: [PATCH 5/6] docs: clarify how options get applied / extended --- docs/get-started/basic-content.qmd | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) 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. From 16a83e1bade0ae0d20000009cc6e17a6486d50c8 Mon Sep 17 00:00:00 2001 From: Michael Chow Date: Mon, 11 Sep 2023 11:23:27 -0400 Subject: [PATCH 6/6] docs: tweak quarto yaml --- docs/_quarto.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 11f81872..40c2d9e0 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -80,7 +80,7 @@ quartodoc: style: pkgdown dir: api package: quartodoc - options: + options: &defaults show_bases: true render_interlinks: true sidebar: "api/_sidebar.yml" @@ -100,6 +100,7 @@ quartodoc: desc: | Renderers convert parsed docstrings into a target format, like markdown. options: + <<: *defaults dynamic: true contents: - name: MdRenderer