Add a doc example for an io.ascii writer with fixed width and commented header - #17630

Thank you for your contribution to Astropy! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.

• Do the proposed changes actually accomplish desired goals?
• Do the proposed changes follow the Astropy coding guidelines?
• Are tests added/updated as required? If so, do they follow the Astropy testing guidelines?
• Are docs added/updated as required? If so, do they follow the Astropy documentation guidelines?
• Is rebase and/or squash necessary? If so, please provide the author with appropriate instructions. Also see instructions for rebase and squash.
• Did the CI pass? If no, are the failures related? If you need to run daily and weekly cron jobs as part of the PR, please apply the "Extra CI" label. Codestyle issues can be fixed by the bot.
• Is a change log needed? If yes, did the change log check pass? If no, add the "no-changelog-entry-needed" label. If this is a manual backport, use the "skip-changelog-checks" label unless special changelog handling is necessary.
• Is this a big PR that makes a "What's new?" entry worthwhile and if so, is (1) a "what's new" entry included in this PR and (2) the "whatsnew-needed" label applied?
• At the time of adding the milestone, if the milestone set requires a backport to release branch(es), apply the appropriate "backport-X.Y.x" label(s) before merge.

meta: I think I'm recognizing the issue as a case of the diamond problem. The root issue seems to be that header and data classes share code via inheritance, instead of composition; which is a much larger with the fundamental design. I know we won't address this anytime soon (it's a massive undertaking, in particular because of huge backward compatibility concerns), but I wanted to seize the opportunity to raise awareness on the question.

Otherwise, and pragmatically, this looks good to me !

Somewhat out of scope, but while you are in this section... I noticed that the examples above don't actually run. They are missing the imports and the format name already exists, so you get an exception trying to register. So:

• Add imports
• Prefix format name with custom_.

@neutrinoceros : It looks like a diamond problem, but it's not. Parsing a fixed-width table is fundamentally different because you have to parse several lines (on writing, even the entire table) to see how many characters the longest value in each column is. That makes the code so different that you can't just reuse the normal commented header. Also, for reading this problem is ill defined. What do we expect for a fixed-width-commented header?

#   a  b
----- --
  100 23

or

#   a  b
# --- --
  100 23

or

#   a  b
--- --
100 23

or some other variant? Sure, you can "just try them all" but I can see already so many ambiguous cases, that it's essentially guaranteed to give wrong results in many cases. As an example for how to write, that better.

Also note you can kind of make reader by composition, it doesn't have to be pure inheritance: See the latter two examples in this section: https://docs.astropy.org/en/latest/io/ascii/read.html#advanced-customization

@taldcroft Unfortunately, the two requirements you ask for are mutually incompatible: The earlier examples are not run as doctest because they don't have the >>> that doctest and doctestplus use to identify runnable examples. If I remove those from the new example, it won't be run any longer and if I want to existing example to run (which I agree is a good idea!) then I'll have to add those markers.

Fortunately, that's exactly why we have that little "copy" button on all code examples in the docs. It used javascript to strip markup and output from the doctest example and copies just the code itself: