search

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

Reconsider where to place ``format_docstring`` function and think about why it's necessary #630

Open evrose54 opened 2 weeks ago

evrose54 commented 2 weeks ago

Requested Update

Description

In PR #465 we introduce a function called format_docstring to create_plugin_registries.py. This function is used to remove double newline characters from docstrings so they read easier via the CLI. We should first discuss where we want to place this function in the first place. It's currently in create_plugin_registries.py as we format the docstrings before we place them in the registry. This way we don't have to do it every time we call the CLI. Considering create_plugin_registries.py is a module used to generate plugin registries, this might not be the best location for this function. In retrospect, this could be, and is being, used in other locations in the code and we should most likely move this to geoips_utils.py or some other utility location.

We should also discuss what we'd like to format and if it's necessary in the first place. IMO, I'd prefer we have some sort of formatting functionality as the raw output of docstrings (specifically packages) is quite ugly. Maybe we just go in and fix the docstrings manually, or maybe we do something else.

Background and Motivation

This issue stems from this comment about PR #465.

Alternative Solutions

Leave the code as is.

Code to demonstrate issue

create_plugin_registries:format_docstring in PR #465.

Checklist for Completion

jsolbrig commented 1 week ago

This relates to #572. I don't know why we're seeing the issues mentioned in #572 but we should figure out why the problem is occuring and address the root cause.

@evrose54 If we need to sit down and look at this together, we should do that. I have a feeling that this is related to some arcane python knowledge that is tickling my brain right now.

evrose54 commented 1 week ago

We may need to rethink how we are implementing the docstrings in our module plugins. I think these are being interpreted in a raw format which would explain why we are seeing all of these extra newlines. Specifically, we should look at geoips.create_plugin_registries:add_module_plugin function which handles adding docstrings to the registry, which the CLI uses.