NRLMMD-GEOIPS / geoips

Main Geolocated Information Processing System code base with basic functionality enabled.
https://nrlmmd-geoips.github.io/geoips/
Other
13 stars 10 forks source link

Update ``geoips get / describe`` docstring attribute format #572

Closed evrose54 closed 3 weeks ago

evrose54 commented 1 month ago

Requested Update

Description

When running geiops get / describe plugin ... (a good example is geoips get plugin algorithms single_channel, the output of the docstring attribute is poorly formatted. This is a combination of the code reading in the docstring in it's raw format, and appending new lines where not necessary. We should apply some formatting for this attribute in all get / describe calls to clean up this output.

Background and Motivation

This stems from a conversation about #444.

Code to demonstrate issue

(geoips) (base) [evan@spring geoips]$ geoips get plugin algorithms single_channel

docstring: 'Data manipulation steps for standard "single_channel" algorithm.

          Generalized algorithm to apply data manipulation steps in a standard order

          to apply corrections to a single channel output product.

          '
family: list_numpy_to_numpy
interface: algorithms
package: geoips
plugin_type: module_based
relpath: plugins/modules/algorithms/single_channel.py
signature: (arrays, output_data_range=None, input_units=None, output_units=None, min_outbounds='crop',
          max_outbounds='crop', norm=False, inverse=False, sun_zen_correction=False, mask_night=False,
          max_day_zen=None, mask_day=False, min_night_zen=None, gamma_list=None, scale_factor=None)
jsolbrig commented 1 month ago

It would probably be nice to keep the exact formatting of the docstring from where it is defined without the extra newlines. I figure the intentional formatting that the author gives to the docstring is probably the best we'll easily get. To support that, maybe multiline docstrings could go under the docstring: portion like this?

(geoips) (base) [evan@spring geoips]$ geoips get plugin algorithms single_channel

docstring: 
    Data manipulation steps for standard "single_channel" algorithm.

    Generalized algorithm to apply data manipulation steps in a standard order
    to apply corrections to a single channel output product.

family: list_numpy_to_numpy
interface: algorithms
package: geoips
plugin_type: module_based
relpath: plugins/modules/algorithms/single_channel.py
signature: (arrays, output_data_range=None, input_units=None, output_units=None, min_outbounds='crop',
          max_outbounds='crop', norm=False, inverse=False, sun_zen_correction=False, mask_night=False,
          max_day_zen=None, mask_day=False, min_night_zen=None, gamma_list=None, scale_factor=None)

while single-line docstings could go on the same line:

docstring: Data manipulation steps for standard "single_channel" algorithm.
family: list_numpy_to_numpy
interface: algorithms
package: geoips
plugin_type: module_based
relpath: plugins/modules/algorithms/single_channel.py
signature: (arrays, output_data_range=None, input_units=None, output_units=None, min_outbounds='crop',
          max_outbounds='crop', norm=False, inverse=False, sun_zen_correction=False, mask_night=False,
          max_day_zen=None, mask_day=False, min_night_zen=None, gamma_list=None, scale_factor=None)