I am not conviced at all that such a complex new API is needed, as opposed to documenting something like

plt.pie([1, 2, 3], radius=1, wedgeprops={"width": .1})
plt.pie([4, 5, 6], radius=.9, wedgeprops={"width": .1})

Wasn't there a donut example somewhere in the gallery? I just found this one which misses the point of using the width parameter - which is really the only thing needed for a donut.

If there is none, maybe take something like this (adapted from my SO answer and add it to the gallery:

import matplotlib.pyplot as plt
import numpy as np

fig, ax = plt.subplots()
ax.axis('equal')
width = 0.3

cm = plt.get_cmap("tab20c")
cout = cm(np.arange(3)*4)
pie, _ = ax.pie([120,77,39], radius=1, labels=list("ABC"), 
                 wedgeprops=dict(width=width, edgecolor='w'), colors=cout)

cin = cm(np.array([1,2,5,6,9,10]))
labels = list(map("".join, zip(list("aabbcc"),map(str, [1,2]*3))))
pie2, _ = ax.pie([60,60,37,40,29,10], radius=1-width, labels=labels,
                  wedgeprops=dict(width=width, edgecolor='w'), 
                  labeldistance=0.7, colors=cin)

plt.show()

Thinking about it, maybe the existing nested_pie example should be kept and modified to have a hole in the center? Then the text could just be adapted and contain the word "donut chart", such that the example is found in search engines under that name?

Hey all,

Thanks for the quick feedback of my PR. Just thought I should give it some more context. Originally, I had noticed confusion from some online posters trying to make donut charts. Solutions varied greatly, and involved anything from dropping a circle in the middle of pie charts to drawing multiple nested pies as described in the example code posted above.

Basically, because 'donut' was the commonly searched term for these types of charts, I wanted to allow users to use this word as a flag to easily create them, which could easily be done using axes.pie.

Interesting to see that this may just be a documentation issue, and also that wedgeprops actually handles adjusting the width property.

Anyways, thanks again for the feedback, and I apologize if it seemed my PR was misguided.

No worries for the PR. If there's a reasonable feature that you can't figure out how to do, but can actually be done easily, that still qualifies as a valid documentation issue (or at least "documentation improvement request"). We just want to try to keep the actual matplotlib API at a reasonable size...

@story645 I think the agreement is to not make an API change but just improve the docs? (a new feature doesn't really qualify as a API change either, I think.)

But it's got a new kwarg? I think that's an API change...unless the kwarg is gonna go away?

I think both @ImportanceOfBeingErnest and myself believe (well, I'm certain for myself :p) that the new kwarg should not be added.

I don't think whether or not I personally like or dislike this matters in any ways; so rather to give some argument here:

This PR adds some kind of donut-API inside the pie-API. Such nested APIs are difficult to maintain and difficult to grasp for users. There are already some similar constructs within matplotlib, the "worst" being the annotate arrows. However those are pass-on arguments supplied to existing objects (like the FancyArrowPatch) which have a clear structure and (maybe not so clear) documentation.

This donut-API is a virtual thing. There is no Donut object anywhere, so it essentially does something which can be achieved with existing means already. In that sense it seems more useful to promote the existing capabilities instead of adding a new path of achiving the same thing.
So what we can take from this PR is that an example case for a donut chart should be in the docs to allow people to find and use it.
I mentionned two options:

• Add a new example
• Modify the existing example

Which one would you prefer?

Of course your opinion does matter :)
I'd rather modify the existing example as having np.inf examples doesn't particularly help either, but I don't have a very strong opinion on that matter.

I gave it a shot at #10953 .

We also have a (very domain specific) variant on this in the examples already (https://matplotlib.org/gallery/specialty_plots/leftventricle_bulleye.html?highlight=bullseye)

@AlexCav Even though we are not going to merge this thank you for your work and identifying a use case we can easily do but was not well documented. Hopefully this will not dissuade you from contributing again in the future!