I'm explicitly not allowing toggling, or changing who you share with, just going from "not-shared" to "shared". Indeed, allowing unsharing makes the problem much more complex.

The use case hinted above is:

  A A A
B X X X
B X X X
B X X X

Each A plots the distribution (histogram) of variable a in conditions a1, a2, a3; each B plots the distribution of variable b in conditions b1, b2, b3, and each X plots the joint distribution (scatter plot). Here you want to sharex across rows and sharey across columns, except that the first row does not share y's and the first column does not share x's (let's say you don't want to normalize your histograms).
Right now if you want to do this you basically need to give up on subplots() and manually add axes in a loop while keeping track of who to share with what -- and that info needs to be passed immediately.
With the PR here, you can start by calling subplots(), then create the required share-linkages.

I understand your example, but it would be helpful if you actually provided one in the PR.

Do you mean one as comments in the code? (where?) in the commit message?

I meant as an example in the example folder

Sure, added a simple example.

First thoughts on this:

1. The API, with a simple sharex() method, is reasonable. I would not advocate prepending set_. More descriptive alternatives would be sharex_with() and sharex_from(). The latter has the advantage of noting that info (objects to be shared) will come from the argument, not go to it.
2. It seems like unsharing could be added by supporting the None argument, and replacing the shared objects with deep copies of them; but I haven't looked at this in detail.
3. Leaving aside the unsharing, which I agree does not have to be addressed here, I think the present approach would work fine when used early--immediately after Axes creation--but inevitably users will find ways to make it surprise them. For example, if two Axes are created, each is called with set_aspect(1, adjustable='datalim'), and then some time later they are shared, the problem won't be caught until draw(), when apply_aspect() is called.

I guess I'm +0.5 on sharex_with() and +0.25 on sharex_from() (both are better than sharex()), let's see what others think.

What about adding something like

Note that this method is only intended to be called immediately after the axes has been created; unexpected behavior may occur if the axes already has its own aspect ratio, formatters, or locators set up.

to the docstrings? (I don't really intend to support "later" calls with this PR anyways.)

rebased

We seem to be getting a systematic failure--not just on this PR--in the macosx build on Travis, in test_bbox_inches_tight_raster[pdf], an image comparison failure.
In addition there are the two circleci docs failures here. Any idea what is going on? @QuLogic?

macOS failure is #17065; doc failure is just spurious inability to download a Sphinx inventory.