Add proper documentation about FITS header effects

[teutoburg]

After @janusbrink and I spent the last hour or so debugging various missing keywords, we discovered that adding an ExtraFitsKeywords effect solves many of those. While the root cause of this is arguably #305, we also concluded that especially for new users, it is not inherently obvious how the FITS header effects work. There are some useful docstrings and IIRC also a notebook somewhere, but it would be good to add a separate page in the ScopeSim docs, explaining the basic idea behind these effects and how to properly set them up, including a few examples. Should then also make the process of #305 smoother.

[hugobuddel]

Yes.. Sounds like you are now in the perfect position to update the documentation :-).

The idea is kinda like:

• ScopeSim is instrument agnostic, so e.g. we should be able to simulate also Euclid data or whatever.
• All these instruments have different header requirements, even when they can reuse Effects.
• So those header keywords cannot be defined in ScopeSim itself, but in the instrument-specific IRDB.
• That is where the ExtraFitsKeywords effect comes in.

There are other keyword Effects, but those are for ScopeSim internal matters. Which probably leads to duplication of information in the headers, but that is fine.

Then about the FitsHeaderKeywords itself there are some concerns:

• The granularity of the FitsHeaderKeywords should probably be the same as the granularity of the other yaml files. Otherwise ScopeSim will try to add headers for Effects that might not be included.
• It is preferable to have the header values refer to values actually used or calculated by effects through #-strings. It is also possible to refer to the ScopeSim input through !-strings, but that is (possibly) less accurate. Because these header keywords usually represent what actually happened during the observation, not what should have happened.