Expose erfa constants from erfam.h and use them in Time - #3137

@jwoillez - In #3141 you mentioned commit jwoillez@d41c149 that exposed the constants in erfam.h. I now included this here and changed Time and EarthLocation to make use of them. Thanks!

@taldcroft - could you have a quick look at the usage of constants from erfam.h in Time? I went perhaps a bit overboard in also using the MJD zero point and seconds per day from erfa, but I guess the benefit is that it makes Time futureproof even for the eventuality that the IAU decides to redefine MJD or the length of the day...

@eteq - and conversely, for this PR, which makes only small changes to erfa.py, there is no real reason to wait for #3159, correct?

@mhvk - Above is a pull request addressing @taldcroft's suggestion to include constant docstrings from erfam.h.

@jwoillez - thanks for the PR, lovely to have the documentation for the constants included!

👏 @jwoillez

Just for heck's sake: I wondered if it is easy to expose the documentation in the constant's docstring. I tried the most naive way,

ELB = (1.550519768e-8)
"""L_B = 1 - d(TDB)/d(TCB), and TDB (s) at TAI 1977/1/1.0"""

(and ELB.__doc__ = ...) but this doesn't work, perhaps because float.__doc__ is not writable. So, it would need wrapping? Ping our python guru: @embray

http://stackoverflow.com/questions/20227051/how-to-document-a-module-constant-in-python

@taldcroft - Great, so a very simple addition of a : would expose the constants in the sphinx documentation! Though even better of course would be to have it be in the docstring... A bit more of a search doesn't turn up anything useful, so it may be that this would require subclassing float and int, which is perhaps a bit much! Anyway, not really important; great to just have the constants available in the first place!

In most of the rest of Astropy, where applicable, I've written

foo = 123
"""Docstring goes here."""

which Sphinx should pick up.

@embray, @taldcroft - I was hoping for the even better case where help(erfa.ELB) would give the docstring (just like the help for functions). That seems a bit less easy and is arguably not quite worth it (but I'll think about it nevertheless...).

Anyway, for now, it may be best to follow the rest of astropy and use the doc-string after the constant instead of #:

Yeah, there is no syntax built into Python for documenting individual objects (module-level or otherwise). The string under the variable assignment is just a convention Sphinx understands. Won't help for help(). I've thought a lot about how to design some kind of proxy object that would enable this, and I suspect others have thought about it too, but there aren't many good possibilities.

There have been some discussions taking place the last several weeks in Python-ideas and python-dev about customizing attribute access on modules which might help somewhat, but only somewhat (well, it could help immensely, but it depends on what form the final product ends up taking, if anything is even changed at all which it might not).

@mhvk - could you finish this up and label as 'ready for final review' once it's ready?

@astrofrog - I think this is ready as is. With the #:, the comments should appear in the documentation and I think this is slightly clearer than the docstring below (though I can easily change that of course). But I was really waiting for a conclusion on the erfa stuff. E.g., it would probably be handier to rebase after #3173 goes in, if that is the one we converge to. @eteq, @embray - should I indeed wait for that, or is it fine for this one to go in first?

I would say wait for #3173, because astropy/astropy-helpers#112 is up, which should be what we need to get the auto-generation stuff running

Now rebased after #3166 went in, so no longer adds a new erfa.py. Ready for final review...

👍

This should only get in after #3173 is merged!

Alright, #3173 is in, so rebase when ready, @mhvk.

This may also conflict with #3217 due to earth.py, but it should be pretty easy to rebase because the changes in #3217 are just renaming from erfa_time names to erfa.

OK, rebased and travis is happy. I think this is ready to go in. @eteq - are you ok with rebasing #3217 after this is in? As you write, either direction is easy, really. But this PR should help make SkyCoord more dimension-independent as well.

Sure, I'll just merge this now seeing as how it's ready.