See also #25998.

@anntzer yes I agree we should add a fig.annotate method.

Also this is lightweight enough that we should document how this works b/c I find the artist API just a bit intimidating.

also is the linting check running off main and so won't see this exception?

Artist instantiation + add_artist should not be a first-class user-facing API. The standard pattern in matplotlib are functions to create the artists. I'd be very reluctant to dilute this. Frist and foremost I consider add_artist a low level API, that end-users should not have to use. It should be the very exception in examples and only show up in corner cases for which it is not worth having high-level API. If advertised in such a scenario, we should communicate that we use low-level API.

Artist instantiation + add_artist should not be a first-class user-facing API. The standard pattern in matplotlib are functions to create the artists

So is that a second yes for @anntzer's proposal of a figure.annotate? As far as I can tell, the implementation is basically forward to artist + add artist to figure & if so I'll just update this PR to do that and then update these docs to show that.

I just wanted to document how you get figure level rainbow text and annotation b/c folks request it and I've needed at least the rainbow text a few times.

Consensus on the call this week was to add Figure.annotate