Documentation of altaz is unclear

The documentation for the altaz function states:

Compute (alt, az, distance) relative to the observer’s horizon

The altitude returned is an Angle in degrees above the horizon, while the azimuth is 
the compass direction in degrees with north being 0 degrees and east being 90 
degrees.

Whereas on the positions and coordinates page, it says:

Azimuth measures the angle around the sky from the north pole, so 0° means that the 
object is straight north, 90° indicates that the object lies to the east, 180° means 
south, and 270° means that the object is straight west.

I think the part ...the azimuth is the compass direction... seems to contradict the Azimuth measures the angle around the sky from the north pole... part because the first statement implies that the azimuth is in reference to magnetic north, and the second implies true north (which I assume is the correct reference point given the changing nature of magnetic north…?).

Other than changing the documentation for clarity, it could potentially be very useful to have true north vs magnetic north as an argument to the altaz function (because sometimes all you have is a compass). And even better as a this-is-asking-a-lot-to-ask-I-know-but-it-would-be-really-helpful-to-beginners suggestion 😉, is to include some discussion of true north vs magnetic north vs grid north on the https://rhodesmill.org/skyfield/positions.html#apparent-position page . This is an awesome software package and what I really appreciate (and think differentiates this from others) is the effort made on this website to explain concepts, as opposed to simply providing an API reference - it really - like, really!!! - helps with ‘easing into’ using the package.

[brandon-rhodes]

the effort made on this website to explain concepts

Thank you, I am glad you have found the documentation helpful!

implies that the azimuth is in reference to magnetic north

You are right. It had entirely escaped me that mentioning a “compass” might imply magnetic north. I’ll get the documentation fixed!

true north vs magnetic north as an argument to the altaz function

That’s an interesting idea, but I think it would be just as simple to have users do subtraction on the azimuth value themselves if they need it adjusted, and doing so will keep Skyfield and its API and code simpler.

some discussion of true north vs magnetic north vs grid north

I will add a mention there at least that there are two kinds of north, but I might simply link to the Wikipedia for folks who need further information about the difference. I would expect a geographic Python library, rather than an astronomy one like Skyfield, to add routines about computing with magnetic north.

I’ll reference this issue once I have the docs updated!

[charlie0389]

Just to be more precise about the webpage about compasses pointing true north: https://www.ngdc.noaa.gov/geomag/faqgeom.shtml#Does_the_compass_needle_point_toward_the_magnetic_pole