Getting started section with code examples in the docs?

[cdeil]

It would be nice to show a few simple code examples in the docs.

Currently there's a lot of text (see here), but I much prefer the hand-on style of the Astropy docs with a getting started section (see e.g. here).

[svw26]

Hello, I agree. I am a first-time user and had to do quite a bit of trial-and-error to get the area of a polygon out. Some comments that may be of help:

1. It took me a while to see this link -- http://spacetelescope.github.io/spherical_geometry/spherical_geometry/ -- at the very top of the 'home page'. Why not add it to the README also?

2. Does the code still work with Python 2.7 or not? That's what it says here http://spacetelescope.github.io/spherical_geometry/spherical_geometry/user.html#requirements but the 'Requirements' section of the README says otherwise.

3. I originally set up my arrays like so:
   points = [(315.4, 18.1), (308.3, 23.0), (314.0, 30.0), (326.4, 30.0), (315.4, 18.1)]
   polygon = SphericalPolygon.from_radec(points, (316.0, 25.0) ) # After the vertices, it says I need to specify an 'inside' point, yet Python complained that "ValueError:all the input array dimensions except for the concatenation axis must match exactly"
   That's when I delved into the polygon.py script and realised that I actually need to do the following:
   lon = [315.4, 308.3, 314.0, 326.4, 315.4]
   lat = [18.1, 23.0, 30.0, 30.0, 18.1]
   polygon = SphericalPolygon.from_radec(lon, lat)

Thanks for making this tool available, but please provide some easy example scripts :) Apologies if you have and I just missed them!

[mcara]

@svw26 Thank you for suggestions and we will definitely take them into account. To the best of my knowledge, the package should work in Python 2.7 though we may discontinue support for Python 2.7 soon.

With regard to the third point, I agree that documentation could significantly be improved.