The example still works fine. If it needs to be updated, that can be done. Since this is the only example of custom projections with a non-affine component and non-rectangular boundaries, it is pretty useful. The fact that it is largely similar to some part of matplotlib's internal code is no argument to remove it, because it's hard enough to understand it in the stand-alone case - if people are then in addition required to find out which parts of the source code they do need and which others they don't, it will be even harder.

I would rather make the library version easier to read (further improvements are welcome) and point users to it (the rendered docs have a [source] link, after all) rather than having two subtly different implementations of the same thing.

+/-0 on removing. The example is still hard to learn from. A simpler example would be better. Could also benefit from some sectioning and explanatory texts (sphinx-gallery) not only code comments. But we don't have that either.

I agree with @timhoffm. The current example is too complicated for most people to learn from, so may as well not have the maintainance burden of keeping it in docs. Is there a use case of a custom projection that would make a good toy example?

One shouldn't underestimate the usecase where you just copy, paste and run an example without understanding it and then just replace bits and pieces until you get your desired result ("learning by doing", "training-on-the-job").
I therefore stressed that it is important that this example uses a non-affine transform and non-rectangular boundaries.
(An example using non-custom, affine transforms and a regular boundary would be SkewT-logP diagram: using transforms and custom projections)

Clearly, if someone has a better idea for this, other than the geographic use case we currently have, that would work as well. (But maybe it's also easier to maintain an example which is close to the source code than one that is further away?)

One shouldn't underestimate the usecase where you just copy, paste and run an example without understanding it and then just replace bits and pieces until you get your desired result ("learning by doing", "training-on-the-job").

We could certainly even split the various geo projections implementations each in their own file to make them independently copypastable. And even then, right now you can just open geo.py and copy its first 305 lines and get a self-standing implemenation of Aitoff projection (that's just because it's the first one there) that you can play with.

(But maybe it's also easier to maintain an example which is close to the source code than one that is further away?)

The point is that they have not been maintained together: they have drifted apart throughout the years.