Clean up help message style and contents

[melanieclarke]

Closes #9676

Class docstrings for Step and Pipeline classes get used as the summary in the command-line help message (e.g. strun flat_field -h).

Clean up, remove, or relocate step and pipeline docstrings that don't format well with -h.

Tasks

• If you have a specific reviewer in mind, tag them.
• add a build milestone, i.e. Build 12.0 (use the latest build if not sure)
• Does this PR change user-facing code / API? (if not, label with no-changelog-entry-needed)
  • write news fragment(s) in changes/: echo "changed something" > changes/<PR#>.<changetype>.rst (see changelog readme for instructions)
  • update or add relevant tests
  • update relevant docstrings and / or docs/ page
  • start a regression test and include a link to the running job (click here for instructions)
    • Do truth files need to be updated ("okified")?
      • after the reviewer has approved these changes, run okify_regtests to update the truth files
• if a JIRA ticket exists, make sure it is resolved properly

[melanieclarke]

Regtests:
https://github.com/spacetelescope/RegressionTests/actions/runs/16452228137

All passing.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.28%. Comparing base (0372411) to head (0a6e722).
⚠️ Report is 288 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9686      +/-   ##
==========================================
+ Coverage   81.26%   81.28%   +0.01%     
==========================================
  Files         368      368              
  Lines       37499    37501       +2     
==========================================
+ Hits        30475    30484       +9     
+ Misses       7024     7017       -7     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[pllim]

I like the concept, but at a glance, I am not sure if all the new text will be formatted properly. We should go to the rendered doc for this PR and make sure the formatting is actually correct.

[pllim]

FWIW LGTM thanks!

[melanieclarke]

@tapastro - this PR is also ready for review

[tapastro]

Looks good from a help message perspective, but it seems a shame to remove some of the expanded explanations for step paramters. Would it be worth preserving them in a dedicated long-form comment after the spec definition, or do you not think they add enough value?

[melanieclarke]

Looks good from a help message perspective, but it seems a shame to remove some of the expanded explanations for step paramters. Would it be worth preserving them in a dedicated long-form comment after the spec definition, or do you not think they add enough value?

I checked before I removed them -- they're all captured in the arguments documentation for the step in RTD. I don't think we need them in both places.