column_descriptions with shorter descriptions for FITS headers

[sbailey]

Context / the Problem

desidatamodel/py/desidatamodel/data/column_descriptions.csv has the reference units and descriptions for every column in the data model. This is used to fill in data model rst files with missing descriptions, auto-generate https://desidatamodel.readthedocs.io/en/latest/column_descriptions.html, and it can be used with desiutil/bin/annotate_fits to add units and descriptions to a pre-existing fits file (e.g. for a VAC). The problem is that many of the descriptions are too long for the FITS format, leading to truncated descriptions that are often lacking key info.

To Do

Create shorter descriptions that would work for FITS headers, which I think means 46 characters max.

Details, details...

Restricting all descriptions to 46 characters would make them more useful for FITS, but likely at the expense of clarity, completeness, and correctness for the primary data model web pages at https://desidatamodel.readthedocs.io. Consider adding another column "ShortDescription", which would be used for FITS headers or other places that need a short description, while still preserving the flexibility to have a longer more complete Description. If ShortDescription is blank, annotate_fits would fall back to using Description instead (which would require a desiutil code update too).

Other variations could be

• Rewrite existing descriptions so that if they are truncated at 46 characters they aren't embarrassingly wrong, while still allowing longer descriptions to be used.
• Use "Description" (short) and "LongDescription" as column names. That would avoid needing a desiutil update (it would keep using the "Description" column), but desidatamodel.update (wrapped by bin/update_column_descriptions) would need to be updated.
• Create a separate column_descriptions_short.csv file (risks getting out of sync with main file, requiring two files to be updated when a new column is added; I don't like this option)

i.e. there is both editorial work to be done to write short column descriptions, and code work for how to ingest short vs. long descriptions in different places.

[stephjuneau]

@sbailey , @weaverba137 : I'm working on a branch to update the CSV file but will not be touching the code to read the short vs. long descriptions. I'm leaning toward keeping the "Description" column as the long descriptions for the Readthedocs (meaning that the previous code wouldn't need to change), and adding a new column called "Description_short" or perhaps "Description_FITS" to indicate a 46-character or fewer description for FITS files. Feel free to already comment on this plan before I get too far along :-)

[weaverba137]

I want to highlight a comment that @sbailey made that may have been buried. The CSV file has to work with both desidatamodel and desiutil. My preference would be to avoid having to modify both packages.