Improve reference docs #7279

NickCrews · 2023-10-02T18:54:14Z

Just some small things that have been missing from the docs that have been bothering me for a while.

ibis/expr/types/relations.py

ibis/expr/api.py

This is to make these other APIs more discoverable.

make these more easily findable/understandable by pandas users

Before it could be interpreted that this returned Column objects. But it just returns string names of the columns. Per review comment, I'm not putting in the full `list[str]` type annotation because it should get rendered in quartodoc, it just isn't.

This is such a central class that it should have a docstring.

NickCrews · 2023-10-03T17:08:29Z

Thanks for the review @cpcloud! I applied all your suggestions.

NickCrews · 2023-10-03T17:10:51Z

ibis/expr/types/generic.py

@@ -116,21 +184,26 @@ def cast(self, target_type: dt.DataType) -> Value:

        return op.to_expr()

-    def try_cast(self, target_type: dt.DataType) -> Value:
+    def try_cast(self, target_type: Any) -> Value:


IDK if you saw this type hint change @cpcloud. The old one was overly-restrictive. It might be nice if the dtype module exported some type alias for TypeLike = Union[dt.DataType, str, np.dtype, ...] so that here and in other places we could consume it.

I think this is fine for now. We may want to use protocols for this specific case, as SupportsDataType at the user level is a well-defined set of things (internals are different story, there are a ton of things that are convertible to ibis DataTypes).

the one set of examples wasn't rendering because interactive mode was off, and it wasn't very useful anyway because it wasn't acting on concrete data.

cpcloud

Nice!

NickCrews · 2023-10-06T21:31:38Z

@cpcloud
Per machow/quartodoc#284, we could get type annotations on Table.columns by adding

Attributes
----------
columns
        a copy of the existing docstring

to Table.__doc__. What do you think, is this duplication worth it?

docs: improve cross-linking within reference

5cb3da6

NickCrews force-pushed the important-docstrings branch from ee56306 to 141d966 Compare October 2, 2023 19:01