Document mpl_toolkits.axes_grid1.anchored_artists

[sargas]

Here's another PR following up on #4864.

The documentation isn't built with this commit, but I'll
push another commit (or open another PR if this is already merged) to add the API docs
to doc/mpl_toolkits/axes_grid/api/index.rst once PR #4864 is merged.

[tacaswell]

please leave the six import even if it isn't used to keep our files consistent.

[mdboom]

I think this is ready to merge once you address @tacaswell's minor comment.

[sargas]

@mdboom sure, but could we hold off until #4864 is merged? It adds a axes_grid1 section to doc/mpl_toolkits/axes_grid/api/index.rst that would be useful to also change in this PR.

[tacaswell]

merged #4864 cycled open/close to re-trigger travis on new master

[sargas]

I've rebased, readded the six import, and enabled the docs to be built in the latest commits.

I did have to change one of the examples which imported matplolib.offsetbox.AnchoredText from mpl_toolkits.axes_grid1.anchored_artists, where it was removed as an unused import. I don't know how API-breaking this is if anyone copied that example.

[tacaswell]

Is it worth moving this code to an example?

[tacaswell]

I am 50/50 on restoring these unused imports.

On one hand it is bad to confuse the API like this by moving classes around between modules.

On the other hand, this is an api break.

In either case 👍 on changing the example to not use this.

[sargas]

The code in if __name__ == "__main__": is the only place where AnchoredText and AnnotationBbox are used, so I figured that as the reason for their being imported. Looking further into it, both are imported in lib/mpl_toolkits/axes_grid/anchored_artists.py, so maybe they are meant to be part of the axes_grid{,1} APIs.

Strangely, AnnotationBbox starts in matplotlib.offsetbox in 80fb71a despite being added in axes_grid (AnchoredText is also moved in that commit without explaination). The demo for it doesn't use axes_grid at all.

I'll re-import those classes and add the imports to __all__, since I think a cleanup of the API is outside the scope of this PR.

[QuLogic]

Backported to v2.x via ef06f5f.