Extend documentation on custom compositors

Feature Request

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

I am trying to add a custom compositor and it is not trivial to understand how this should be implemented. The use of existing compositors is now well-documented (thanks @pnuu in #705) but for a developer wanting to add their own compositors documentation is still limited. Specifically, I'm trying to convert two fogpy compositors fogpy.composites.fls_day and fogpy.composites.fls_night, which are a few dozen lines each and interface to classes within the 1.5 kLOC fogpy.algorithms module. The fogpy compositors are built around the old mpop package and .cfg configuration files. From the fogpy documentation, I infer that those functions then became methods of an image attribute of an mpop scene.

Today, I think I need to code my own Compositor class, probably inheriting either GenericCompositor or CompositeBase, defining at least the __call__ method. I believe the two functions in the linked fogpy module will essentially translate to this method. I may also need to define __init__. From reading the source, I have the impression that the prerequisites field in the YAML-file are passed into the projectables argument of the __call__ method, but maybe some things get passed into __init__ as well.

My inference is mostly from reading the source and some conservations in the Pytroll slack.

Describe the solution you'd like

I would like that the developer guide part of the Satpy documentation grows a new section with a tutorial on "adding a custom compositor so Satpy". This should be closely related to the composites documentation added in #705, and ideally explain (either directly or by linking to existing or to-be-written documentation elsewhere):

• when a composite does or doesn't need a custom compositor;
• what interface defines a compositor class, including:
  • documentation for all methods inputs and outputs, and
  • how these translate to the fields for composites in the YAML file;
• guidance on what existing class to subclass from (CompositeBase, GenericCompositor, or maybe another one);
• advice on how this class should be documented;
• and advice on how this class should be tested.

This list may be incomplete.

Describe any changes to existing user workflow

Most users will be unaffected, but new developers needing to create new compositors will be helped.

The documentation will grow larger, which will mean there is more documentation to keep up to date in case things change. This will increase the price of API changes for Satpy developers and therefore make their life harder. Perhaps the increase in price of API changes will reduce their frequency, which will be a secondary benefit to users ;-)

Additional context

As I am trying to find out how to do it, I will write down my thought process, probably in comments to this issue. Some thoughts I have already written down in this initial comment. Those thoughts, as far as they are correct and perhaps even where they are not, as long as they are useful, should be useful to write a first draft of such compositor documentation.

Start with the developer guide and the composites documentation from #705, then inspect the CompositeBase and GenericCompositor interfaces, including how YAML prerequisites relate to compositor inputs. Done means a tutorial explains when to use a custom compositor, its interface and YAML mapping, subclass choice, documentation guidance, and testing advice.