Add documentation for mpl_toolkits.axes_grid1.inset_locator

[sargas]

This module has some nice, undocumented (except in narrative form) helpers that has been interesting to figure out.

I made some formatting changes, and some slight API differences:

1. AnchoredSizeLocator and AnchoredZoomLocator both overrode __call__ merely to save the axes (which is unused in AnchoredSizeLocator anyways). I moved the saving of this value to the __call__ of their superclass. No other file in matplotlib uses these classes, and the superclass doesn't look used for anything else online.
2. inset_axes and zoomed_inset_axes take a **kwarg, but the only keyworded argument that would not result in an error is borderpad. I changed the functions to make that clear.

I still have AnchoredLocatorBase (and its subclasses) to document, but I don't understand the code as is - for instance, a required parameter offsetbox is always unused, and I don't understand why a locator object (something used with Axes.set_axes_locator) would ever have any method except those used by __call__ (making the capabilities inherited from AnchoredOffsetBox useless).

[WeatherGod]

Docbuild failure, but I don't know what it means: https://api.travis-ci.org/jobs/74123925/log.txt?deansi=true

[sargas]

I generated the docs in py3 on my local machine, it turns out the dedent_interpd decorator doesn't like to work on classes in py2.

I moved the class-level docstrings to the __init__ functions; that allows the docs to build here.
I don't know how the python3.3 error (in matplotlib.tests.test_backend_ps.test_savefig_to_stringio_with_usetex) could have happened though.

[WeatherGod]

Ok, that makes sense. Don't worry about that usetex test, it is a transient
one that has to do with the Travis system.
On Aug 4, 2015 8:59 PM, "Joseph Booker" notifications@github.com wrote:

I generated the docs in py3 on my local machine, it turns out the
dedent_interpd decorator doesn't like to work on classes in py2.

I moved the class-level docstrings to the init functions; that allows
the docs to build here.
I don't know how the python3.3 error (in
matplotlib.tests.test_backend_ps.test_savefig_to_stringio_with_usetex)
could have happened though.

—
Reply to this email directly or view it on GitHub
#4864 (comment)
.

[tacaswell]

Awesome!

I have no problem with this sneaking in under the wire for 1.5, but do not have time to review.

[WeatherGod]

A question for the other devs... Is there any reason why we continue to have the axes_grid and axes_grid1? From my understanding, axes_grid is "deprecated" and is only kept around for compatibility. Documentation-wise, it looks like only the axes_grid module is actually generated.

[jenshnielsen]

I would be 👍 on removing axes_grid

[tacaswell]

Has anyone been able to review this?

[tacaswell]

@leejjoon Can you review this?

[tacaswell]

please leave the six import

[tacaswell]

Gave this a quick read, looks really good 👍

There are a bunch of places where things need to be put under a Notes section for numpydoc to render them nicely.

In the places where **kwargs is eliminated, it should be checked that all possible keyword args really are covered.

[sargas]

Thanks for reviewing this.

I don't think the kwargs should go into Notes, since the keyworded arguments are parameters.

I attempted to do the following in Parameters:

    kwargs
        Patch properties for the lines and box drawn:
        %(Patch)s

This doesn't quite get the formatting right either (the start of the description is misaligned with the start of the descriptions of the other parameters). The generated HTML has an extra <blockquote> element causing this.

[tacaswell]

I think the priority should be that the docs render reasonably even if they are not semantically correct.

[sargas]

Okay. I've also double checked the **kwargs options I removed.

[tacaswell]

This is what the built docs look like http://matplotlib.org/devdocs/mpl_toolkits/axes_grid/api/inset_locator_api.html

[tacaswell]

back-ported to 1.5.x as 8677af6