docs: add callout notes for some APIs changes and additions #10551
Conversation
ibis-docs-bot
bot
removed
the
docs-preview
|
Hmm, I think actually it's a bit hard to see down at the bottom. Maybe it would be better if the notes were right before the Parameters section so it's easier to see, it doesn't take up much room. If there were every any detailed notes, the call-out would start collapsed?
|
|
@IndexSeek you had chimed in on the related issue, do you have any thoughts here? |
|
I agree. It might make more sense to move it above the parameters section. That's a good place for it. We don't have any Quarto callout blocks in the other docstrings. I have seen the Sphinx directives used in docstrings before; I was curious to know if this was common. I think this is a valuable change, but I want to ensure we're not undoing #5347 as you commented on the other issue. |
|
I'll try to take a closer look this week. Broadly on board with adding this information and I think above parameters is a fine place for it. I don't think it's counter to #5347 -- having version related information is fine, we just didn't want the headache of publishing versioned docs. |
NickCrews
force-pushed
the
version-added-callouts
branch
from
e650032 to
7ec3eda
Compare
cpcloud
force-pushed
the
version-added-callouts
branch
from
e965a1a to
640163e
Compare
fixes #10535
Other things I considered:
using some other mechanism, like sphinx versionadded directives
like https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded
but I don't think our doc system uses sphinx. So I think we are limited to using quarto's constructs?
using a different callout type
There is warning, tip, etc. I thought note made the most sense.
Adding a
@versionaddeddecoratorSimilar to the
@experimentaland@deprecateddecorators in util.py. But I thought adding them inline like this wasn't that hard.Placing the callout in a different place in the docstring
eg further up, where it might be more obvious. But the official python docs put them down at the bottom, so I chose to follow that convention. I think that future-proofs us if there are multiple callouts in a row.
Some sort of autocheck
In future PRs, how can we be sure that docstrings are updated like this? I couldn't think of a good way to do it. Maybe if there is a
breaking-changetag on the issue? but that doesn't work forAdded in versionchanges. I think the best we can do is to just have all maintainers be aware of this. If we like this approach then we can tag in all the maintainers into this issue?