API Document for WCSAxes

A number of packages, such as pywcsgrid2, APLpy, and kapteyn, have developed ways of making plots in world coordinate systems (WCS) in Matplotlib, and since this is a common issue in Astronomy, we are interested in implementing the general problem of plotting WCS axes in the Astropy core, so that we can avoid duplicating this in other packages. The present document describes the proposed API.

The aim is not to provide the simplest possible user-friendly API to the user, but to design a flexible API consistent with the matplotlib API upon which user-friendly tools can be developed.

This API was written by @astrofrog and @leejjoon, and benefited from feedback from @ebressert and @ChrisBeaumont. It is written in markdown, since we wanted to include images. The latest rendered version of the API document (with images) can be seen here:

https://github.com/astrofrog/astropy-api/blob/34889e57f091f7c78d28c2f368ece465c32314aa/wcs/wcs_api.md

At this time, we would be very interested in getting feedback from other developers (or users) regarding this API. In some places, the API may not be optimal, so please let us know if you have any suggestions! Also, if you see anything missing, please let us know (and offer suggestions if possible!).