docs: add callout notes for some APIs changes and additions

[NickCrews]

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 @versionadded decorator

Similar to the @experimental and @deprecated decorators 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-change tag on the issue? but that doesn't work for Added in version changes. 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?

[ibis-docs-bot]

Docs preview: https://pr-10551-e6500326133b8ecbdc94b1b1c8a30c19e9039825--ibis-quarto.netlify.app

[NickCrews]

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?

[NickCrews]

@cpcloud @gforsyth this is ready for review whenever you have a chance! I think I am in favor of moving the call-out to just before the Parameters section, but wanted your confirmation before I made that effort.

[NickCrews]

@IndexSeek you had chimed in on the related issue, do you have any thoughts here?

[IndexSeek]

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.

[gforsyth]

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.

[cpcloud]

Other than the spurious additional newline, LGTM!