I would agree to roughly half of the changes made here. Certainly

from matplotlib.transforms import blended_transform_factory
reference_transform = blended_transform_factory(ax.transAxes, ax.transData)
ax.annotate(...,  xycoords=reference_transform)

is better written as

ax.annotate(..., xycoords=ax.get_yaxis_transform())

However,

ax.annotate(..., xycoords='figure pixels')

is much better than

from matplotlib.transforms import IdentityTransform
ax.annotate(..., xycoords=IdentityTransform())

In general xycoords="axes fraction" is understandable on a much lower level than xycoords=ax.transAxes. It's not for nothing that the transformation tutorial is categorized as "Advanced", while annotations are one of the most basic things you want to be doing with plots.

Removing the "data" value is ok in all examples which do not explicitely focus on annotations. E.g.

• examples/showcase/anatomy.py
• examples/style_sheets/style_sheets_reference.py
• examples/text_labels_and_annotations/mathtext_examples.py
• examples/text_labels_and_annotations/usetex_demo.py

However, in cases which show the functionality of annotations, it adds clear value and points the user to the option to use some other coordinates systems as well. I would hence oppose the changes in

• examples/text_labels_and_annotations/demo_annotation_box.py
• examples/units/annotate_with_units.py
• examples/userdemo/annotate_explain.py

Furthermore at least some of the examples

• examples/userdemo/annotate_simple{*}.py
• examples/userdemo/annotate_simple_coord{*}.py
• examples/userdemo/connectionstyle_demo.py
• examples/userdemo/simple_annotate{*}.py

should keep it. Those are originally part of the annotations guide. It would totally make sense to rework that guide and bring some variety concerning the allowed arguments into it.

At the risk of sounding like a broken record...

In general xycoords="axes fraction" is understandable on a much lower level than xycoords=ax.transAxes.

In my view, this means that we should rename ax.transAxes to something more transparent, e.g. ax.axes_rel_transform. If the name is good, it should not matter for understandability whether it has quotes around or "ax.<>" (and the latter form is tab-completable!). If someone learns how to use "axes fraction" with annotate(), they've learned, well, how to place an annotation in axes fraction coordinates and nothing else, not even how to do that with text(). If someone learns how to use ax.transAxes (name up to bikeshedding) in annotate(), they're pretty close to also knowing how to do

• text(.1, .1, "foo", transform=ax.transAxes) (text in relative coordinates)
• plot([.1, .2], [.1, .1], transform=ax.transAxes) (e.g. for a scale bar)
• imshow([[0, 1], [2, 3]], extent=(0, .5, 0, .5), transform=ax.transAxes)
• etc.

The problem is that somehow _AnnotationBase and all its children got a different API convention that also allows strings. So we have an API mixture and in my opinion we should either in the long term:

1. propagate the string API to other methods
2. deprecate the string API in all methods. Perhaps adding some better-named helpers (i.e. ax.axes_coords, ax.points_coords) to give the user easy access to the transforms.
3. status-quo with Annotation and (many) friends having a different API from other artists.

For now, I'm not convinced that just ripping all the string-based examples out of the documentation base is the right thing to do until we decide what to do about the API. If both APIs are staying as-is, then I'm not sure this PR is the way to go....

Maybe one can separate between the changes that are a clear improvement of the docs and changes that are controversial? I.e. either remove the offending stuff out of this PR, or open a new PR with the helpful and harmless stuff?

The "noncontroversial" parts are in #13549.
I would definitely support option 2 in #13515 (comment) (where the string locations don't even necessarily need to be really deprecated, just "soft deprecated" by making them less prominent in the docs). Obviously I'm not your average matplotlib user, but at least personally I had always found annotate() positioning extremely confusing (where do all these strings come from??) until I realized that they were just another way to spell ax.transAxes, etc.
Between strings and ax.transAxes (again, name up to bikeshedding), the latter has two advantages: 1) they are tab-completable, and 2) we need to expose these transforms anyways (well, unless we decide to make them private, but why would we?) so that API is already there.

Since this Pull Request has not been updated in 60 days, it has been marked "inactive." This does not mean that it will be closed, though it may be moved to a "Draft" state. This helps maintainers prioritize their reviewing efforts. You can pick the PR back up anytime - please ping us if you need a review or guidance to move the PR forward! If you do not plan on continuing the work, please let us know so that we can either find someone to take the PR over, or close it.

I've changed my mind, the string args can be quite nice to work with in practice. Some other parts of the PR have now been merged separately anyways.