I don't think the what's new should be updated mostly cause I don't think this will be very discoverable there and also cause I think we try to avoided updating the what's new docs.

Can you please make this an example in annotations and then link the API docs for arrows to it? @timhoffm may have a better suggestion but I'm not sure what the policy is in terms of these kinds of figures in the reference docs.

ETA: Thanks so much for making this figure and putting in the PR, I'm way psyched for it's existence even if I'm being a grump on placement.

I wouldn't have a problem updating "what's new" in this case. This is "only" a visual improvement of an existing plot.

However, I agree that it's not very discoverable in there.

Can you please make this an example in annotations and then link the API docs for arrows to it? @timhoffm may have a better suggestion but I'm not sure what the policy is in terms of these kinds of figures in the reference docs.

Fundamentally, illustrating plots are fine the reference docs, see e.g. the notes section of https://matplotlib.org/devdocs/api/ticker_api.html#matplotlib.ticker.ScalarFormatter. However the example code is quite long and would clutter the docstring. So, placing it in the text/annotations section of the examples and linking in the plot via .. plot:: /path/to/example at https://matplotlib.org/devdocs/api/_as_gen/matplotlib.patches.ArrowStyle.html#matplotlib.patches.ArrowStyle is the best solution here.

Hi @timhoffm and @story645 I've updated the PR with the proposed changes. I created a new example and linked it to matplotlib.patches.ArrowStyle in the example references. I also referenced the example in the ArrowStyle docstring. When I build the documentation it shows up as an example but it does not pull through to https://matplotlib.org/devdocs/api/_as_gen/matplotlib.patches.ArrowStyle.html#matplotlib.patches.ArrowStyle - I assume I'm missing something here so please assist with that.

You've squashed some unrelated commits in here. An easy way to fix is to copy the two files you wanted to change somewhere else, On your branch do git fetch upstream; git reset --hard upstream/main and then copy your two files back to where they belong and make your commit. Alternately, you can do git restore -s upstream/main pathTo/MyFile for the two files.

Hi @jklymak, sorry about that wat trying to follow the process to amend the previous commit. Did not notice the other commit.

git commit --amend --no-edit
git push [your-remote-repo] [your-branch] --force-with-lease

You've squashed some unrelated commits in here. An easy way to fix is to copy the two files you wanted to change somewhere else, On your branch do git fetch upstream; git reset --hard upstream/main and then copy your two files back to where they belong and make your commit. Alternately, you can do git restore -s upstream/main pathTo/MyFile for the two files.

Hi @jklymak, not sure how that commit got entangled with mine. I tried this without avail, received the following:

fatal: 'upstream' does not appear to be a git repository
fatal: Could not read from remote repository.

I went ahead and synced my branch with matplotlib:main from GitHub ("sync fork") and then pulled again but now it looks like some of the changes are already merged, so I'm a bit confused. Not sure what to do now.

Please assist and sorry for the mess.

You need to add a "remote" called upstream before you can do that. Our git guide is quite bad, in my opinion. This one is quite good (and I still think we should just copy it, and stop dragging our feet making a new one): https://docs.xarray.dev/en/stable/contributing.html#getting-started-with-git

Hi @jklymak, thanks I managed to set the upstream and then I ran:

git fetch upstream
git reset --hard upstream/main

Then made the changes again on my branch and ran:

git commit --amend --no-edit
git push --force-with-lease

I think it should be good now. Please confirm.

Looks better. Congrats!

So I apologize profusely for doing this now, but I have an idea that might simplify things? Maybe instead of making this a new example (w/ all the annoyances of copying the ArcAnnotation class), this gets folded into the ArcAnnotation example as a second example? And then we title that example something like annotating angles - direction and scale invariance? B/C the direction stuff is what's really useful here as an example, and that the figure makes a good bracket reference is kind of independent...(and yes this then is maybe a tutorial, but that's out of scope here)

You can still keep the link to the figure in the reference using the sphinx gallery reference tags https://sphinx-gallery.github.io/stable/advanced.html#cross-referencing

The failing test doesn't seem related to this PR:

/home/circleci/project/doc/api/prev_api_changes/api_changes_3.6.0/removals.rst:157: WARNING: py:obj reference target not found: SubplotBase.get_subplotspec
/home/circleci/project/doc/api/prev_api_changes/api_changes_3.6.0/removals.rst:158: WARNING: py:obj reference target not found: SubplotBase.set_subplotspec

So I apologize profusely for doing this now, but I have an idea that might simplify things? Maybe instead of making this a new example (w/ all the annoyances of copying the ArcAnnotation class), this gets folded into the ArcAnnotation example as a second example? And then we title that example something like annotating angles - direction and scale invariance? B/C the direction stuff is what's really useful here as an example, and that the figure makes a good bracket reference is kind of independent...(and yes this then is maybe a tutorial, but that's out of scope here)

You can still keep the link to the figure in the reference using the sphinx gallery reference tags https://sphinx-gallery.github.io/stable/advanced.html#cross-referencing

Good suggestion. Alternatively, we could also leave out AngleAnnotation completely (which basically just provides the angle size in this case) and only add the directional arrow. That's what we are really after from the start right, more clarity on the angle direction?

It would then look like this:

Alternatively, we could also leave out AngleAnnotation completely

I'd still like labeling of the angle between bracket and perpendicular, but that can probably be achieved w/ ax.text placed relative to the perpendicular.

Also I really like your suggestion!

Alternatively, we could also leave out AngleAnnotation completely

I'd still like labeling of the angle between bracket and perpendicular, but that can probably be achieved w/ ax.text placed relative to the perpendicular.

Also I really like your suggestion!

Either one is cool, please let me know what the preferred way is 👌🏻

I agree w/ you on leaving out ArcAnnotation, (I really like that it's a simpler way to label angles) but if you're gonna go that route please label the angle with ax.text instead.

Ok, so I've simplified the example significantly by removing AngleAnnotation and adding ax.Text angles. The plot looks like this now:

In the end it's exactly the same output as with AngleAnnotation, just a lot less code.

build failed 'cause of unexpected indent but I'm having trouble finding it in the .py file

/home/circleci/project/doc/gallery/text_labels_and_annotations/angles_on_bracket_arrows.rst:32: ERROR: Unexpected indentation.

eta: probably this line going by the rendered docs

Sorry about that

No problem/apology needed/wish it was easier to find the errors in the logs :/

Um that first commit needs to be removed before I merge this. Can you try rebasing against main and dropping that first commit?

If you need help let somebody (me) know!

Thanks @jacoverster! Congratulations on your first PR to Matplotlib 🎉 We hope to hear from you again.

Thanks @jacoverster! Congratulations on your first PR to Matplotlib 🎉 We hope to hear from you again.
It was a pleasure. Thanks for the guidance @story645 and @jklymak. Would love to contribute more.