I'd be against removing the original example. This is part of thempl_toolkits.axis_artist module documentation. Those toolkit modules are underdocumented anyways, and often enough those examples are the only way to find out how a feature was originally meant to be used.

Instead I'd propose to
a) Move the mpl_toolkits examples even further down in the gallery.
b) In a case like this one, where there would be a better/alternative way to do something similar with the core library, link to it, maybe even recommending to use the linked example.

If the point of axisline_style is to draw arrows at the ends of ticks, I'd rather deprecate it -- as this shows, this can be reasonably achieved with standard tools, and then we won't have people asking about why rcParams don't apply to them as in#17157. (One alternative would be to consider the fact that rcParams don't apply as a bug and hope that someone fixes it, but I don't even want to think about the backcompat issues there. An other alternative being as always to not bother about API consistency but heh.)

It seems the main motivation for the axisline stuff is to have a decoupled set of artists, where spines, but also ticks can have arbitrary orientations, instead of the standard spines. The ZeroSubplot just seems to be an easy consequence of that concept.
My point is, it's not necessary to even bother about it... If you keep it encapsulated in its module and don't mix documentation, it can live on as it is. I'm sure there are people using it.

The only thing we really want at this point is to not confuse users, hence my proposal from above.

Do you want to take over this PR then? Your docs proposal above is still an improvement, but I'll leave it to you (or anyone else who wants to do it :))

Ok, I created#17180.

The order of section in the gallery still needs to be done, but I would first need to think about that for a bit, so that PR may come later.

Superseded.