docs: improve docstrings on methods using the database param
#11112
Conversation
github-actions
bot
added
docs
There was a problem hiding this comment.
Thanks for improving the docs, @NickCrews ! One (copy-pasted) spelling error to fix, and I think we should case DuckDB when using it in prose.
I also need to check if ipython style "superhelp" correctly pulls docstrings from the parent class (I'm pretty sure it does, but I remember some issues a while back)
Update: superhelp works just fine.
| >>> con = ibis.duckdb.connect() | ||
| >>> foo = con.create_table("foo", schema=ibis.schema(dict(a="int"))) |
There was a problem hiding this comment.
Hmm, is it weird that all backends list_tables will show a duckdb example?
There was a problem hiding this comment.
It's slightly weird. We can probably DOCTEST: +SKIP these and just make a 100% handcrafted example. The API output of list_tables is very stable.
There was a problem hiding this comment.
I don't think this needs to be done in this PR though.
There was a problem hiding this comment.
If we make a different example for every backend, then this is going to lead to drift in docstrings between backends. This drift is bad, because specific backends often have not very good docstrings. This already happens, and in this PR I attempt to reduce this drift. I would rather have one place where the docstring is defined, I don't think this is too confusing, I think it should be fairly obvious that they can replace ibis.duckdb.connect() with ibis.datafusion.connect() and everything else will be the same.
|
The PR title and description conform to the Conventional Commits specification. |
NickCrews
force-pushed
the
database-docs
branch
2 times, most recently
from
e364f80 to
6e4909c
Compare
NickCrews
force-pushed
the
database-docs
branch
2 times, most recently
from
d20e674 to
2d80b4f
Compare
|
To get the datafusion tests to pass, I had to dig into getting the current database and catalog for datafusion. I ended up implementing this, and adding |
|
@NickCrews This seems to break a lot of datafusion functionality for reasons that are unclear to me. |
NickCrews
force-pushed
the
database-docs
branch
from
2d80b4f to
1391c58
Compare
…atalog or database param of list_tables()
This was breaking tests because it all of a sudden made impala get run for some tests, but this functionality isn't implemented. I will do this in a different PR.
This is breaking.
I removed many docstrings from subclasses, which should lead to them inheriting the docstring of the base class. This should make the docstrings easier to maintain and less lilely to drift.
I also linked to the concepts doc that @gforsyth wrote, but that never was included in the index or linked to anywhere. I think it should be surfaced somewhere more obvious.