diff --git a/python/docs/_renderer.py b/python/docs/_renderer.py index 8f75fda0d..85b2a296d 100644 --- a/python/docs/_renderer.py +++ b/python/docs/_renderer.py @@ -2,7 +2,6 @@ import quartodoc.ast as qast -from contextlib import contextmanager from griffe.docstrings import dataclasses as ds from griffe import dataclasses as dc from tabulate import tabulate @@ -19,6 +18,14 @@ except ImportError: from griffe import dataclasses as expr +skip_annotation_types = [ + "kaskada", + "kaskada.destination", + "kaskada.results", + "kaskada.windows", + "pyarrow", +] + def _has_attr_section(el: dc.Docstring | None): if el is None: @@ -117,19 +124,26 @@ def _render_table(self, rows, headers): @dispatch def render_annotation(self, el: str) -> str: + print(f"render str: {el}") return sanitize(el) @dispatch def render_annotation(self, el: None) -> str: + print("render none") return "" @dispatch def render_annotation(self, el: expr.Name) -> str: - return f"[{sanitize(el.source)}](`{el.full}`)" + print(f"render name: {el} {el.full}") + if el.full not in skip_annotation_types: + return f"[{sanitize(el.source)}](`{el.full}`)" + return "" @dispatch def render_annotation(self, el: expr.Expression) -> str: - return "".join(map(self.render_annotation, el)) + print(f"render expr: {el}") + text = "".join(map(self.render_annotation, el)) + return text.lstrip(".") # signature method -------------------------------------------------------- @@ -301,7 +315,7 @@ def render(self, el: dc.Parameters): @dispatch def render(self, el: dc.Parameter): - print(f'Parameter: {el}') + print(f'Parameter: {el} anno: {el.annotation}') # TODO: missing annotation splats = {dc.ParameterKind.var_keyword, dc.ParameterKind.var_positional} has_default = el.default and el.kind not in splats @@ -468,32 +482,22 @@ def render(self, el: ds.DocstringSectionRaises): return self._render_definition_list("Raises:", rows, title_class="highlight") - # @dispatch - # def render(self, el: ds.DocstringReturn) -> str: - # returns = [] - # return_type = self.render_annotation(el.annotation) - # if return_type: - # returns.append(return_type) - - # return_desc = sanitize(el.description, allow_markdown=True) - # if return_desc: - # returns.append(return_desc) + @dispatch + def render(self, el: ds.DocstringSectionAdmonition) -> str: + print(f'Admonition: {el.title} {el.value.description}') - # returns_text = " -- ".join(returns) - # if returns_text: - # return self._render_definition_list("Returns:", [returns_text], title_class="highlight") - # else: - # return "" + rows = [] + if el.title.lower().startswith("note"): + rows.append(f'::: {{.callout-note title="{el.title}"}}') + elif el.title.lower().startswith("warn"): + rows.append(f'::: {{.callout-warning title="{el.title}"}}') + else: + rows.append(f'::: {{.callout-tip title="{el.title}"}}') - @dispatch - def render(self, el: ds.DocstringRaise): - # similar to DocstringParameter, but no name or default - annotation = self.render_annotation(el.annotation) - return f'{annotation} -- {sanitize(el.description, allow_markdown=True)}' + rows.append(el.value.description) + rows.append(':::') - @dispatch - def render(self, el: ds.DocstringSectionAdmonition): - return sanitize(el.value.description, allow_markdown=True) + return "\n".join(rows) # unsupported parts ---- diff --git a/python/docs/autosummary.py b/python/docs/autosummary.py index 8311e9c28..963f08a4d 100644 --- a/python/docs/autosummary.py +++ b/python/docs/autosummary.py @@ -217,7 +217,6 @@ def build(self, filter: str = "*"): self.write_doc_pages(pages, filter, hierarchy) # inventory ---- - print(hierarchy) # update paths in items for item in items: @@ -243,9 +242,6 @@ def build(self, filter: str = "*"): if location: item.uri = f'{self.dir}/{location}/{path}#{fragment}' - for i in range(10): - print(f'Item: {items[i]}') - _log.info("Creating inventory file") inv = self.create_inventory(items) if self._fast_inventory: diff --git a/python/pysrc/kaskada/_timestream.py b/python/pysrc/kaskada/_timestream.py index 7aabea57c..349281698 100644 --- a/python/pysrc/kaskada/_timestream.py +++ b/python/pysrc/kaskada/_timestream.py @@ -996,8 +996,8 @@ def round(self) -> Timestream: Returns: A Timestream of the same type as `self`. The result contains `null` - if the value was `null` at that point. Otherwise, it contains - the result of rounding the value to the nearest integer. + if the value was `null` at that point. Otherwise, it contains + the result of rounding the value to the nearest integer. Notes: This method may be applied to any numeric type. For anything other @@ -1026,9 +1026,9 @@ def greatest(self, rhs: Arg) -> Timestream: Returns: Each point contains the value from `self` if `self` - is greater than `rhs`, otherwise it contains `rhs`. - If any input is `null` or `NaN`, then that will be - the result. + is greater than `rhs`, otherwise it contains `rhs`. + If any input is `null` or `NaN`, then that will be + the result. See Also: This returns the greatest of two values. See @@ -1045,9 +1045,9 @@ def least(self, rhs: Arg) -> Timestream: Returns: Each point contains the value from `self` if `self` - is less than `rhs`, otherwise it contains `rhs`. - If any input is `null` or `NaN`, then that will be - the result. + is less than `rhs`, otherwise it contains `rhs`. + If any input is `null` or `NaN`, then that will be + the result. See Also: This returns the least of two values. See @@ -1110,8 +1110,8 @@ def write( Returns: An `ExecutionProgress` which allows iterating (synchronously or asynchronously) - over the progress information, as well as cancelling the query if it is no longer - needed. + over the progress information, as well as cancelling the query if it is no longer + needed. """ raise NotImplementedError @@ -1178,7 +1178,7 @@ def run_iter( Returns: Iterator over data of the corresponding kind. The `QueryIterator` allows - cancelling the query or materialization as well as iterating. + cancelling the query or materialization as well as iterating. See Also: - [](`~kaskada.Timestream.write`): To write the results directly to a @@ -1217,7 +1217,7 @@ def explain( Returns: A GraphViz representation of the execution plan as a string, SVG string, or SVG. - Specific representation depends on the `format` argument. + Specific representation depends on the `format` argument. Raises: ValueError: if the `kind` is not recognized or the `format` is not supported.