Add high-level docs for compound regions

[joleroi]

This PR

• adds a short code example in the getting started section of the high-level docs to illustrate compound regions
• adds a fancy image to the selfsame section

Ready for review

[cdeil]

@joleroi - Thanks!

I put a version of the docs here:
https://www.mpi-hd.mpg.de/personalhomes/deil/public/regions/pr-74/getting_started.html#compounds

Currently (for me, on Python 3 with latest Astropy), the plot looks like this:

Should there be points outside the regions?
Or is there an effect (shift, center vs edge, WCS distortions) you hadn't intended?
I didn't look at the code that makes the plot yet, if you want to discuss it, come by my office.

Travis-ci fails are unrelated, I think:
https://travis-ci.org/astropy/regions/jobs/174955597#L743

[cdeil]

Left two minor inline comments.

[cdeil]

Usually one puts stuff as it would appear in the Python console.
I.e. only put ... for input.
This line is output and should not have ... or be indented.
Same for print statement below.

[cdeil]

Please add a one-line description at the top of every new file.
People will copy & paste it and then it's good to have a one-line description if they find it in their Download folder a month later.
Something like:

"""
Example script illustrating compound regions.
"""

[joleroi]

@cdeil I can hit Dismiss review ... very tempting!

[joleroi]

Should there be points outside the regions?
Or is there an effect (shift, center vs edge, WCS distortions) you hadn't intended?

I don't think there should be points outside the regions. I check manually for the following point

<SkyCoord (Galactic): (l, b) in deg
    (358.0, 6.0)>

It is marked in red (and called strange point in the legend) in the plot

I am pretty sure that it is really and XOR point so the compound region contains method seems to work

In [12]: from astropy.coordinates import SkyCoord, Angle

In [13]: from regions import CircleSkyRegion

In [14]: # define 2 sky circles
    ...: circle1 = CircleSkyRegion(
    ...:     center=SkyCoord(1,2, unit='deg', frame='galactic'),
    ...:     radius=Angle('5 deg')
    ...: )
    ...:
    ...: circle2 = CircleSkyRegion(
    ...:     center=SkyCoord(-4,3, unit='deg', frame='galactic'),
    ...:     radius=Angle('3 deg'),
    ...: )
    ...:

In [15]: test_coord = SkyCoord(358, 6, unit='deg', frame='galactic')

In [16]: test_coord.separation(circle1.center) <= circle1.radius
Out[16]: array(True, dtype=bool)

In [17]: test_coord.separation(circle2.center) <= circle2.radius
Out[17]: array(False, dtype=bool)

So I guess there is some unwanted behaviour in the plotting method of CircleSkyRegion. @astrofrog @larrybradley - @cdeil said you're experienced with this kind of issues 😁. Any ideas?

[cdeil]

Looks like a sky circle matplotlib plotting issue to me.
The script @joleroi wrote is OK, but the output isn't, as far as I can see.

[joleroi]

The test failures are not related to changes in this PR, see e.g.
https://travis-ci.org/astropy/regions/jobs/175035799#L787
@astrofrog @larrybradley Ok to merge this and discuss the problem with the plotting in a separate issue/PR?