Improve findability of example plots in the docs

[cdeil]

Currently via the astroplan.plots API docs, it's clear that we currently have three plots ... here's the API docs:

• plot_airmass
• plot_parallactic
• plot_sky

The Plotting with Astroplan section does include examples for plot_airmass and plot_sky, but not for plot_parallactic (it mentions it, but no example shown). It took me a while to find an example of plot_parallactic ... it's in a parallactic angle section in the summer triangle tutorial

One thing that can be improved easily would be to link from the docstrings of the plot functions to the sections of the docs that contain examples of that plot.

Concerning the fact that no example parallactic plot is in the "Plotting with Astroplan" section, I'm not sure. Either add one (or move it from the summer triangle tutorial), or link to the existing example in the summer triangle tutorial.

[jberlanga]

@cdeil I didn't want to overwhelm the user with repetitive examples all on the same page (since plot_airmass and plot_parallactic work quite the same way), but of course you're right that it should be easier to find an example.

I can fix this by linking to the existing plot or just assigning the different plot types to their own page and show the full range of plots possible for each type--any preferences?

[cdeil]

I can fix this by linking to the existing plot or just assigning the different plot types to their own page and show the full range of plots possible for each type--any preferences?

Thanks!
I don't have a preference ... you decide!

The main point is that a new user should be able to find an example plot for each plot function quickly just starting from the top-level docs page by clicking or the search field.

[bmorris3]

I think it would make the most sense to have an example on the Plotting With Astroplan page, even if it's similar to the one on the Summer Triangle page. The Plotting With Astroplan page will be a reference that you can go to for all of the examples.

[bmorris3]

One thing that can be improved easily would be to link from the docstrings of the plot functions to the sections of the docs that contain examples of that plot.

To double-check, would it be sufficient to include include links in the plot_* docstrings to the Plotting with Astroplan rtd tutorials?

[cdeil]

To double-check, would it be sufficient to include include links in the plot_* docstrings to the Plotting with Astroplan rtd tutorials?

yes.