From 8e685241a5c15c83c6356d15d0ad723a2d50054b Mon Sep 17 00:00:00 2001 From: Joe Cheng Date: Tue, 27 Aug 2024 16:50:57 -0700 Subject: [PATCH] Quartodoc 0.7.6 (#1636) --- Makefile | 2 +- docs/_renderer.py | 38 +++++++++++++++++++++++--------------- pyproject.toml | 4 ++-- 3 files changed, 26 insertions(+), 18 deletions(-) diff --git a/Makefile b/Makefile index f89477142..22a67d7cd 100644 --- a/Makefile +++ b/Makefile @@ -39,7 +39,7 @@ clean-build: FORCE rm -fr dist/ rm -fr .eggs/ find . -name '*.egg-info' -exec rm -fr {} + - find . -name '*.egg' -exec rm -f {} + + find . -name '*.egg' -exec rm -rf {} + # Remove Python file artifacts clean-pyc: FORCE diff --git a/docs/_renderer.py b/docs/_renderer.py index 22695ac30..4d7299398 100644 --- a/docs/_renderer.py +++ b/docs/_renderer.py @@ -9,9 +9,17 @@ from typing import Literal, Optional, TypedDict, Union import quartodoc.ast as qast -from griffe import dataclasses as dc -from griffe import expressions as exp -from griffe.docstrings import dataclasses as ds +from griffe import ( + Alias, + DocstringAttribute, + DocstringParameter, + DocstringSectionParameters, + DocstringSectionText, + Expr, + ExprName, + Function, + Object, +) from plum import dispatch from quartodoc import MdRenderer from quartodoc.pandoc.blocks import DefinitionList @@ -42,7 +50,7 @@ def render(self, el: qast.DocstringSectionSeeAlso): return prefix_bare_functions_with_func(el.value) @dispatch - def render(self, el: Union[dc.Object, dc.Alias]): + def render(self, el: Union[Object, Alias]): # If `el` is a protocol class that only has a `__call__` method, # then we want to display information about the method, not the class. if len(el.members) == 1 and "__call__" in el.members.keys(): @@ -78,7 +86,7 @@ def render(self, el: Union[dc.Object, dc.Alias]): return converted @dispatch - def render(self, el: ds.DocstringSectionText): + def render(self, el: DocstringSectionText): # functions like shiny.ui.tags.b have html in their docstrings, so # we escape them. Note that we are only escaping text sections, but # since these cover the top text of the docstring, it should solve @@ -93,7 +101,7 @@ def render_annotation(self, el: str): # TODO-future; Can be removed once we use quartodoc 0.3.5 # Related: https://github.com/machow/quartodoc/pull/205 @dispatch - def render(self, el: ds.DocstringAttribute): + def render(self, el: DocstringAttribute): row = [ sanitize(el.name), self.render_annotation(el.annotation), @@ -106,15 +114,15 @@ def render_annotation(self, el: None): return "" @dispatch - def render_annotation(self, el: exp.Expr): - # an expression is essentially a list[exp.ExprName | str] + def render_annotation(self, el: Expr): + # an expression is essentially a list[ExprName | str] # e.g. Optional[TagList] # -> [Name(source="Optional", ...), "[", Name(...), "]"] return "".join(map(self.render_annotation, el)) @dispatch - def render_annotation(self, el: exp.ExprName): + def render_annotation(self, el: ExprName): # e.g. Name(source="Optional", full="typing.Optional") return f"[{el.name}](`{el.canonical_path}`)" @@ -122,7 +130,7 @@ def render_annotation(self, el: exp.ExprName): # Overload of `quartodoc.renderers.md_renderer` to fix bug where the descriptions # are cut off and never display other places. Fixing by always displaying the # documentation. - def summarize(self, obj: Union[dc.Object, dc.Alias]) -> str: + def summarize(self, obj: Union[Object, Alias]) -> str: # get high-level description doc = obj.docstring if doc is None: @@ -131,7 +139,7 @@ def summarize(self, obj: Union[dc.Object, dc.Alias]) -> str: docstring_parts = doc.parsed if len(docstring_parts) and isinstance( - docstring_parts[0], ds.DocstringSectionText + docstring_parts[0], DocstringSectionText ): description = docstring_parts[0].value @@ -164,7 +172,7 @@ def summarize(self, obj: Union[dc.Object, dc.Alias]) -> str: # Consolidate the parameter type info into a single column @dispatch - def render(self, el: ds.DocstringParameter): + def render(self, el: DocstringParameter): param = f'{el.name}' annotation = self.render_annotation(el.annotation) if annotation: @@ -178,14 +186,14 @@ def render(self, el: ds.DocstringParameter): return (param, el.description) @dispatch - def render(self, el: ds.DocstringSectionParameters): + def render(self, el: DocstringSectionParameters): rows = list(map(self.render, el.value)) # rows is a list of tuples of (, ) return str(DefinitionList(rows)) @dispatch - def signature(self, el: dc.Function, source: Optional[dc.Alias] = None): + def signature(self, el: Function, source: Optional[Alias] = None): if el.name == "__call__": # Ex: experimental.ui._card.ImgContainer.__call__(self, *args: Tag) -> Tagifiable sig = super().signature(el, source) @@ -302,7 +310,7 @@ def is_no_ex_decorator(x): # Don't throw for things that can't be decorated return - if not el.is_explicitely_exported: + if not el.is_exported: # Don't require examples on "implicitly exported" functions # In practice, this covers methods of exported classes (class still needs ex) return diff --git a/pyproject.toml b/pyproject.toml index 4643bdaea..5689e8697 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -120,8 +120,8 @@ doc = [ "tabulate", "shinylive", "pydantic>=2.7.4", - "quartodoc==0.7.5", - "griffe<1.0.0", + "quartodoc>=0.7.6", + "griffe>=1.1.1", ] [project.urls]