Add "References"-column to Satpy's Documentation Reader-table

[sjoro]

Feature Request

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

Browsing Satpy's documentation I often find myself checking the available readers-table: https://satpy.readthedocs.io/en/stable/index.html#id1

It would be nice to have an extra column after fsspec support to have link(s) to relevant format spec or resources which would be helpful with the reader. Some reader's offer References in their respective module, e.g. seviri_l1b_hrit and seviri_l1b_native, but this is a bit more work to dig out in the documentation through readthedocs. Extra column in the table would give a quick and easy way to find relevant documentation for the reader.

Caveats to this proposal are, of course, 1) not all the readers have a reference document listed in the respective reader-module, so for many readers this column would be empty... probably for a long time. 2) in general, keeping links up-to-date is next to impossible, which might frustrate users if the links are not working. 3) more work on Satpy-devs to add these references to respective reader yaml-file... could be potentially be spread out to multiple contributors by requiring a reference to be added if a PR is coming in for a certain reader. 4) readers for future instruments don't typically have publicly available documentation until very close to launch 5) what to do if there are multiple references/resources available? will the table be horrible to read?!?

Describe the solution you'd like Extra column in Satpy available readers-table for relevant documentation for the reader.

Describe any changes to existing user workflow None. reader yaml-files would need to be updated with a reference or resource-tag, e.g.

reader:
  name: seviri_l1b_hrit
  short_name: SEVIRI L1b HRIT
  long_name: MSG SEVIRI Level 1b (HRIT)
  description: >
    HRIT reader for EUMETSAT MSG (Meteosat 8 to 11) SEVIRI Level 1b files.
  status: Nominal
  supports_fsspec: true
  sensors: [seviri]
  default_channels: [HRV, IR_016, IR_039, IR_087, IR_097, IR_108, IR_120, IR_134, VIS006, VIS008, WV_062, WV_073]
  reader: !!python/name:satpy.readers.yaml_reader.GEOSegmentYAMLReader
  reference: https://www-cdn.eumetsat.int/files/2020-04/pdf_fg15_msg-native-format-15.pdf

reader_table.generate_reader_table would need to be updated to pull this extra info to the table.

Just a suggestion, to get discussion going

[sjoro]

@ameraner pointed out that something similar is done in the docs for resampling... maybe we could add a column with a link to the module instead... https://satpy.readthedocs.io/en/latest/resample.html#resampling-algorithms

[djhoese]

The difficulty with a link to the module is that not all readers have their own module or have one single module or are represented by one class. You have the higher-level Reader class (YAML reader or the segmented readers, etc) then you have the file handlers which could be different for each file type in the reader. Then you have things like HRIT readers where they may have their own module with a custom class and/or file handlers but there is more information in the hrit_base.py module about how to use the reader or other things to know.

[mraspaud]

In the same way that we make the table dynamically, could we add the description and references provided in the yaml files visible eg by "unfolding" the current line in the table? I'm thinking something like in the cf convention's standard name table here: https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html