astropy / astropy/astropy

Refactor FITS table docs

Open
#3,782 2 comments 0 reactions 0 assignees View on GitHub
Docs Effort-medium io.fits Package-expert
Dominant language
Python
Stars
5.3k
Forks
2.2k
Avg merge
1d 19h
Merged PRs (30d)
75

Description

I receive a whole category of FAQs, similar to spacetelescope/PyFITS#101 (no reason I'm picking on it specifically other than that it's the most recent example), that go something like: "I tried to create a FITS table by creating a bunch of `Column` objects, and something or other didn't work."

The problem is that the current docs for creating FITS tables, much of which is inherited from earlier versions of PyFITS that were less flexible, emphasize a workflow that requires a lot of direct fussing with the FITS format: One has to specify column formats using the old FORTRAN-like format codes, and often involving other quirks like getting setting the correct TDIMn keywords for multidimensional columns, and just generally more fussing than is usually really necessary.

These interfaces should still be documented, as they are useful for cases where the user needs very fine control over how the FITS format is written. But in most cases this is not necessary, and what PyFITS does automatically is completely sensible. So the docs should first emphasize how tables can be created from Numpy structured arrays, or by using the Astropy Table interface (this is already brought up in #3552, but we need to go even further than that).

To go even further, there might be some room for improving the the API on this front. For example, rather than manually creating `Column` objects it should be good enough, in most cases, to pass in a list of arrays, along with maybe a list of column names (similar to the existing interface for creating `Table` objects).

Contributor guide

Open the contributing guide

Research direction

Review the current FITS table creation documentation and its examples, then compare the structured-array and Astropy Table workflows with the existing Column-based guidance. Done means the docs lead with the simpler workflows while retaining the low-level format-control interfaces; the possible list-of-arrays API change is a separate design question.

Written by the indexing model from the issue text.

Assessment

Tech stack
numpy, python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.