Improve documentation on overlays

[gerritholl]

Feature Request

Is your feature request related to a problem? Please describe.

I find the documentation on how to add overlays difficult to follow. I know I can pass a keyword argument overlay={...} to Scene.show or Scene.save_dataset, that this method then calls satpy.writers.add_overlay, which in turn will call trollimage, which will in turn call pycoast. I don't know how the pycoast documentation informs me on what to put in the overlay dictionary.

• The Scene.save_dataset documentation refers to the documentation for satpy.writers.add_overlay. The difference between overlays and decorations is not explained here. If I remember correctly overlays are in geolocated coordinates whereas decorations are in image coordinates.
• The satpy.writers.add_overlay definition has the keywoard arguments color, width, resolution, level_coast, level_borders, fill_value, grid, and overlays.
  • Only the arguments color, resolution, and grid are documented.
  • The documentation for color is incorrect: it says that color should be a 3-element tuple, but the string "red" also works.
  • Presumably level_borders may impact whether only national or also subnational borders are drawn, but this is not explained.
  • There is an example using the keyword argument overlay but the function definition uses overlays. I suppose that this keywoard argument is assumed to be passed to Scene.show(...) or Scene.save_dataset(...) but this is not clear, it might also be a typo in the documentation.
  • From the source code, it appears that color, width, resolution, grid, level_coast, and level_borders are deprecated and the argument overlays should be used instead, but there appears to be no information on how.
• There is no explanation on how to draw borders in one colour and coastlines in another, if at all possible.
• The satpy documentatation claims that is documented in detail with pycoast, but a search for level_borders yields no results at this time, nor does major_lonlat which is used in the example with grid. The pycoast usage examples do not cover usage through the satpy interface. The pycoast API documentation has a ContourWriterAGG and a CounterWriterPIL; satpy creates a ContourWriterAGG object and then calls apply_pil from trollimage so I'm not sure which one is used. It's not clear how to translate what is documented for pycoast into arguments passed on through satpy. In case I missed something, a direct deep link to where I should look in the pycoast documentation would be useful.

Describe the solution you'd like

I would like that the most future-proof API to interface pycoast from Satpy is clearly documented, with examples on how the interface is defined. When Scene.save expects a keyword a overlay and calls add_overlay which expects a keyword overlays which calls trollimage which interfaces pycoast through its classes, how does the pycoast documentation inform the user on exactly what to put in the overlay dictionary?

Describe any changes to existing user workflow

Improved documentation should have only positive effects.

Additional context

I am still trying to figure out how to configure the details of adding overlays, until I know how to do this I can't write the improved documentation myself.

Much of this probably applies identically to decorations, I just haven't tried those.

[gerritholl]

Although https://satpy.readthedocs.io/en/stable/writing.html#adding-text-to-images now contains hints on how to add text to images (added by @simonrp84 in #2517), this could still be extended to include information on coastlines and a lat/lon grid (for example).