sphinx warnings from wcs when building docs in py 3.3

[eteq]

I noticed the following sphinx warnings when building the docs in python 3.3:

/Users/erik/src/astropy/docs/api/astropy.wcs.UnitConverter.rst:10: WARNING: error while formatting arguments for astropy.wcs.UnitConverter: 'function' object has no attribute '__mro__'
/Users/erik/src/astropy/docs/wcs/index.rst:179: WARNING: error while formatting arguments for astropy.wcs.UnitConverter: 'function' object has no attribute '__mro__'

This does not appear in 2.7 as far as I know. Any ideas? @mdboom ?

[embray]

I'm not sure why this is only happening on Python 3.3, but I do see what the problem is: UnitConverter (which is a class) is being wrapped with deprecated which actually does not at the moment support class decoration.

I could either fix deprecated to allow deprecating classes in this way, or deprecated should just be used to wrap UnitConverter.__init__ and not the class itself.

[eteq]

It might be in all 3.x, by the way - I only had 3.3 convinient, and we are currently only building the docs with 2.7.

[mdboom]

UnitConverter is an extension class, so it behaves (in all of the important ways) as a function, and thus the deprecated decorator does work.

Python 3.3.2 (default, Nov  7 2013, 10:01:05) 
[GCC 4.8.1 20130814 (Red Hat 4.8.1-6)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from astropy import wcs
>>> wcs.UnitConverter("m", "km")
WARNING: AstropyDeprecationWarning: The UnitConverter function is deprecated and may be removed in a future version.
        Use astropy.units instead. [astropy.utils.misc]
<astropy.wcs.UnitConverter 'm' to 'km' (x*0.001)>
>>> wcs.UnitConverter.__doc__
'\n.. deprecated:: 0.2\n    Use astropy.units instead.\n\nUnitConverter(have, want, translate_units=\'\')\n\n
...[TRIMMED]...

And I can't reproduce the original error by @eteq, with setup.py build_sphinx. Are you building the docs in some other way?

But a larger question: since this has been deprecated since 0.2 already, should we just remove it from 0.4? I guess we still should fix this bug on 0.3, if it in fact exists, but it's a corner case -- it's a very niche feature (access to the unit converting functionality of wcslib) that only applies to Python 3.x. And if it only applies to building the docs (i.e. even for @eteq, the above deprecation warnings at the console work), I'd suggest not investing effort into fixing it.

[eteq]

Weird that you can't reproduce it @mdboom ... I just double-checked and I see it even after completely wiping the astropy build and re-running it with setup.py build_sphinx. Could it be a numpy version number or something (I'm on 1.7.1)?

Regardless, I'm fine with just removing it in 0.4 now that I know its deprecated... As you say, it's a very corner case anyway.

[mdboom]

Do you also have issues trying to reproduce my interpreter session (above), or does this only happen in the context of Sphinx?

[embray]

I get that deprecated works as is. It's just that it turns something that some part of sphinx thought was a class into a function, hence the confusion.

[eteq]

@mdboom - When I run the interpreter session, I see the exact same thing you do, so it's only in the sphinx build. Very strange!

@embray - I think part of the issue may be that UnitConverter.__init__ is actually in the C-level part of WCS, so it can't be easily decorated (although I'm not too good at the C API, so there may be some way I'm not familiar with).

[astrofrog]

@mdboom @eteq - does #2156 fix this?

[mdboom]

Yes. Forgot to close this after merging #2156.