refactor: more detailed deprecated argument warning message

[raph-luc]

I believe users will appreciate a more helpful deprecation message for arguments that we mark as deprecated.

The same logic should be applicable for any arguments that we deprecate and are replaced by newer arguments. If time allows, please help identify any gaps/issues.

Also updated the warning stack level so that it refers to the call that results in the deprecation warning, rather than the source of the deprecation warning in the code (see #2808 (comment) below)

Examples for launch_fluent which is the only method using deprecate_argument at the moment

Before the changes in this PR:

• Any launch_fluent(show_gui=...) specification
  PyFluentDeprecationWarning: 'show_gui' is deprecated. Use 'ui_mode' instead.

After the changes in this PR:

• launch_fluent(show_gui=True):

PyFluentDeprecationWarning: 'show_gui' is deprecated. Use 'ui_mode' instead.
pyfluent.general WARNING: Using 'ui_mode = "gui"' for 'launch_fluent()' instead of 'show_gui = True'.

• launch_fluent(show_gui=False):

PyFluentDeprecationWarning: 'show_gui' is deprecated. Use 'ui_mode' instead.
pyfluent.general WARNING: Using 'ui_mode = None' for 'launch_fluent()' instead of 'show_gui = False'.

• launch_fluent(show_gui=None):

PyFluentDeprecationWarning: 'show_gui' is deprecated. Use 'ui_mode' instead.
pyfluent.general WARNING: Using 'ui_mode = None' for 'launch_fluent()' instead of 'show_gui = None'.

• Both specified e.g. launch_fluent(show_gui=True, ui_mode="gui"): show_gui is ignored and only ui_mode applies (no change of behavior in this PR):

PyFluentDeprecationWarning: 'show_gui' is deprecated. Use 'ui_mode' instead.
pyfluent.general WARNING: Ignoring 'show_gui = True' specification for 'launch_fluent()', only 'ui_mode = "gui"' applies.

For previous discussion see #2800 (comment)

[mkundu1]

I think what we have here is a combination of a warning and an information. We shall warn user that a deprecated arg-name is entered and what is to use instead. I think the message 'show_gui' is deprecated. Use 'ui_mode = "gui"' instead of 'show_gui = True' is somewhat incomplete as we are not telling users what to do for 'show_gui = False'. The previous message 'show_gui' is deprecated. Use 'ui_mode' instead. is better as in that case user will probably look-up the usage of ui_mode in the documentation and will get the full picture.

We shall also inform the user about how the value is converted for the current input, otherwise user may think that the entered value has been discarded and try to re-execute the function again.

So, perhaps we can structure the code in this way:

1. Show warning for the deprecated arg-name usage.
2. Convert deprecated arg-name/value to new arg-name/value.
3. Show information about the above conversion.

[raph-luc]

So, perhaps we can structure the code in this way:

1. Show warning for the deprecated arg-name usage.
2. Convert deprecated arg-name/value to new arg-name/value.
3. Show information about the above conversion.

@mkundu1 do you mean just using a warning print and a separate information print (I imagine you mean something like logging.info()) instead of putting it all together in a single warning message as I suggest here? That is closer to what I was originally suggesting as well (giving the user all the information in a more detailed way), but @seanpearsonuk raised a point that it might be too much information to provide: #2800 (comment) which is a fair point and that is partly why I suggest we be less verbose and more direct as in this PR.

Regardless, this PR already addresses all 3 points in my understanding, for point 1 we show a warning for the deprecated argument: 'show_gui' is deprecated.; point 2 is already handled by the converter function that @prmukherj had included and does the exact conversion from the previous argument to the new one, that is what we are using here; point 3 is the second part of the warning: Use 'ui_mode = "gui"' instead of 'show_gui = True'. which shows the exact conversion performed and what the user should use next time.

Let me know if you want to meet offline to discuss this further

Edit: addressed by 52e6a8e