Add documentation for kwargs passed to reader+writer backends

[dhomeier]

Additional follow up to #1152 in response to #1152 (comment) – @kelle, those are generally backend options and thus depend on what interface the various loaders are using; I have completed the docstrings for the two FITS loaders to specifically point to that. Again, since these are not linked to the processed docs, I put a few examples into the narrative docs (might be preferable to link to the utility functions docs, but parsing_utils again are not included even in the API docs – would be useful to have them also for the custom loader section).

I noticed that we are linking to the astropy-dev docs rather than stable, is this by design?

[kelle]

I think we should add an entire section dedicated to headers with the best practices and caveats. The information you provided in a response to me is a great start. I think the section should also include an example of header round-tripping with tabular-fits. E.g, an example of adding a header to a Spectrum1D object, writing it out, and reading it back in.

Per default it is using meta['header'] both in tabular-fits and wcs1d-fits (in principle it depends on the loader, but those 2 are the only ones that provide a writer at the moment).
With update_header=True it treats the entire meta as a dictionary to update the default header from (i.e. pulls in all items that are serialisable and do not conflict with FITS keyword rules).

[kelle]

I think we should add a section dedicated to headers.

[rosteen]

I noticed that we are linking to the astropy-dev docs rather than stable, is this by design?

That surprises me, certainly not by design on my part. I actually am not even sure where that's specified.

[dhomeier]

The first intersphinx links, for astropy and gwcs, were using latest, those added later stable

specutils/docs/conf.py

Lines 60 to 63 in f77c8df

	intersphinx_mapping['astropy'] = ('https://docs.astropy.org/en/latest/', None)
	intersphinx_mapping['gwcs'] = ('https://gwcs.readthedocs.io/en/latest/', None)
	intersphinx_mapping['reproject'] = ('https://reproject.readthedocs.io/en/stable/', None)
	intersphinx_mapping['mpl_animators'] = ('https://docs.sunpy.org/projects/mpl-animators/en/stable/', None)

so might be accidental.

[dhomeier]

I think we should add an entire section dedicated to headers with the best practices and caveats.

Yes, I think that would be a good follow up PR (i.e. for a future release) for someone with a good grasp of what are now considered best practices, maybe @simontorres?
For this docs fixup I have added a small paragraph with the basics so it is at least documented that a meta exists. ;-)

[kelle]

Minor suggestions.

[kelle]

Suggested change

	Conversely the two provided FITS writers are saving the contents of any
	``Spectrum1D.meta['header']`` (which should be an :class:`astropy.io.fits.Header`
	or any object like a `dict` that can instantiate one) as the header of the
	:class:`~astropy.io.fits.hdu.PrimaryHDU`.
	The two provided FITS writers (`fits-tabular` and `wcs-fits`) save the contents of
	``Spectrum1D.meta['header']`` (which should be an :class:`astropy.io.fits.Header`
	or any object like a `dict` that can instantiate one) as the header of the
	:class:`~astropy.io.fits.hdu.PrimaryHDU`.

[kelle]

Please also add a link to the docstrings of the tabular_fits and the wcs_fits writers. I cant seem to find those currently included in the specutils docs. Maybe that's also a separate PR?

[dhomeier]

I've added the suggestions; there are no API docs to any of the loaders one could link to, and I am afraid this will be non-trivial to amend since they are dynamically loaded through the unified IO framework.
I suppose one could build upon _list_of_loaders to then recursively call Spectrum1D.read.help(format) from its list entries to generate a doc page of all the readers (and writers)...
As mentioned above the parsing_utils functions are missing as well, but that should be more straightforward to fix; just don't know where to add the right hook for Sphinx. But those are more of interest for the Custom Loader documentation. Definitely more than enough stuff for another PR, or two.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 86.87%. Comparing base (d16d91a) to head (52dd41f).
Report is 37 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1157      +/-   ##
==========================================
+ Coverage   86.83%   86.87%   +0.03%     
==========================================
  Files          63       63              
  Lines        4528     4541      +13     
==========================================
+ Hits         3932     3945      +13     
  Misses        596      596              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[rosteen]

Thanks again, LGTM.