Attributes docs in help message

[melanieclarke]

I noticed that a few steps include documentation on "Attributes" in the class docstring. Since that docstring forms the help message for the command-line version of the step, the documentation appears in the help message, poorly rendered. For example, for the flat_field step:

$ strun flat_field -h
usage: strun [-h] [--logcfg LOGCFG] [--verbose] [--debug] [--save-parameters SAVE_PARAMETERS] [--disable-crds-steppars] [--pre_hooks] [--post_hooks] [--output_file] [--output_dir]
             [--output_ext] [--output_use_model] [--output_use_index] [--save_results] [--skip] [--suffix] [--search_output_file] [--input_dir] [--save_interpolated_flat]
             [--user_supplied_flat] [--inverse] [--override_flat] [--override_fflat] [--override_sflat] [--override_dflat]
             cfg_file_or_class [args ...]

Flat-field a science image using a flatfield reference image. Attributes ---------- correction_pars : dict After the step has successfully run, the flat field applied is stored, as {'flat':
DataModel}. use_correction_pars : bool Use the flat stored in `correction_pars`.
...

The attributes docs generally just repeat what is in the "spec" and in the arguments documentation for the step, so they should just be removed wherever they appear. If they contain useful information not recorded elsewhere, they should be moved.

[pllim]

Huh. It is also confusing because those Step subclasses inherit docstring from stipipe Step, so for FlatFieldStep, it lists these 2 attributes on top, but then you also see the inherited attributes in a different subsection in the same docstring.

https://jwst.readthedocs.io/en/latest/api/jwst.flatfield.FlatFieldStep.html

Perhaps Step subclasses should not use its own "Attributes" section at all?

[melanieclarke]

The inherited attributes listed there are class attributes, which are not documented in docstrings anywhere -- I guess sphinx just pulled them out of the code. The inherited instance attributes are not documented. I'm not sure how sphinx compiles attribute documentation from different sources -- maybe there's a way to get them to play nicely together.

But Step subclasses should definitely not use their own Attributes section, or any docstring section other than the summary, because of the help message co-opting.